ShapeWords MCP

Universal MCP server for generating word clouds with ShapeWords.

It exposes ShapeWords rendering tools through the Model Context Protocol, so any MCP-capable client can create SVG, JSON, or PNG word clouds from text, workshop notes, prompts, research snippets, or agent output. By default it uses the hosted ShapeWords Render API; with engine: "skia" it renders locally inside the MCP server with the shared layout core and CanvasKit/Skia.

Tools

All tools use stdio MCP transport.

render_word_cloud

Creates a ShapeWords render job, polls until it is finished, and returns:

• public artifact URL for hosted renders, or a local inline artifact for engine: "skia";
• job metadata;
• optional image content for MCP clients that support image results.

Use this tool for one-shot generation when the caller wants the final artifact.

create_word_cloud_job

Starts a render job and returns the job/status/artifact URLs without waiting.

Use this tool for asynchronous workflows where the client will poll later.

get_word_cloud_job

Checks a render job by ID.

Use this tool with the jobId returned by create_word_cloud_job or render_word_cloud.

Input Schema

render_word_cloud accepts all render options below. create_word_cloud_job accepts the hosted options only: engine: "skia" is local-only and is supported by render_word_cloud.

get_word_cloud_job accepts:

words items use this shape:

Rotation presets:

horizontal, vertical, orthogonal, crossing, crossingVoids, dancing,
positiveSlope, negativeSlope, random, custom, mixed, angled, free

renderProfile: "canvas" sends the same practical defaults as the main editor canvas: shapeType: "cloud", width: 800, height: 600, quality: "hq", maxWords: 700, seed: 0, fontFamily: "Montserrat", minFontSize: 18, maxFontSize: 96, padding: 3, rotationPreset: "orthogonal", spiralType: "archimedean", and fillMode: "fill".

Use renderProfile: "api" only when you need the older compact Render API defaults: circle shape, 1024x640, SQ quality, and 120 max words.

Text Input

The MCP server can send either raw text, explicit words, or both:

• repeated words increase frequency, for example cloud cloud cloud render render API;
• words[] preserves caller-provided weights and avoids differences in tokenization, stop words, or lemmatization;
• when both text and words[] are present, ShapeWords renders from words[] and keeps text as source context;
• paragraphs, meeting notes, workshop notes, prompts, research snippets, and keyword lists are valid;
• files such as CSV, Excel, or Google Sheets are not uploaded through this MCP server; paste or generate the text content first.

Example weighted text:

{
  "text": "MCP MCP MCP ShapeWords ShapeWords word cloud word cloud render API agents tools",
  "shapeType": "cloud",
  "format": "svg",
  "seed": 12345
}

Example explicit weighted words:

{
  "words": [
    { "text": "ShapeWords", "value": 12 },
    { "text": "MCP", "value": 9 },
    { "text": "canvas", "value": 7 },
    { "text": "layout", "value": 6 },
    { "text": "render", "value": 5 }
  ],
  "shapeType": "cloud",
  "format": "svg"
}

Shapes

Use shapeType to choose the word-cloud mask.

Stable built-in shape ids accepted by the production renderer include:

rectangle, circle, heart, star, cloud, diamond, tree, triangle, arrow,
square, pentagon, hexagon, octagon, cross, plus, moon, sun, drop,
flame, leaf, flower, mountain, apple, house, book, camera, music,
chat, location, trophy, rocket, plane, car, shield, lightning, check,
infinity, tag

Built-in brand shape ids include:

brand-product-hunt, brand-y-combinator, brand-hacker-news,
brand-indie-hackers, brand-github, brand-figma, brand-notion,
brand-stripe, brand-vercel, brand-linear, brand-supabase,
brand-railway, brand-netlify, brand-firebase, brand-cloudflare,
brand-airtable, brand-replit, brand-anthropic

The production renderer may also accept additional generated ShapeWords ids. For portable automation, prefer the stable ids above or pass a custom SVG shape.

The local engine: "skia" path currently supports rectangle, square, circle, diamond, triangle, star, heart, cloud, custom SVG shapes, and vendored Font Awesome shape ids such as fa-cat. Unsupported local shape ids are rejected instead of silently changing the requested shape.

Custom Shapes

Set shapeType to custom and provide customShapeDefinition:

Custom heart example:

{
  "text": "love love design care product community team support",
  "shapeType": "custom",
  "customShapeDefinition": {
    "name": "Heart",
    "path": "M 50 90 C 25 70, 0 50, 0 30 A 25 25 0 0 1 50 30 A 25 25 0 0 1 100 30 C 100 50, 75 70, 50 90 Z",
    "viewBox": "0 0 100 100",
    "fillRule": "nonzero"
  },
  "format": "svg"
}

Output

render_word_cloud returns:

• text content with the completed job id and artifact location;
• structuredContent.job with normalized job metadata;
• structuredContent.artifactUrl for hosted renders;
• structuredContent.localArtifact for engine: "skia";
• structuredContent.siteUrl;
• optional MCP image content when returnImage is true and format is svg or png.