ShapeWords MCP

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.

For engine: "skia", render_word_cloud always returns inline MCP image content for format: "png" or format: "svg" because there is no hosted artifact URL.

create_word_cloud_job returns the same metadata immediately after job creation, without waiting for completion.

get_word_cloud_job returns the latest job status and artifact URL.

Generated artifact URLs are short-lived because the ShapeWords Render API stores render jobs in memory.

Format and Engine Notes

• svg is the recommended automation format: it is fast, compact, and works with the browserless shared-core renderer.
• json returns layout data from the same shared-core placement.
• png is rasterized from the same generated SVG/layout, so word placement matches SVG/JSON for the same input and options.
• engine: "auto" is recommended unless you need to force a specific path.
• engine: "browserless" supports svg, json, and png.
• engine: "browser" supports svg and png, not json.
• engine: "skia" is local-only and supported by render_word_cloud. It does not create pollable hosted jobs. Layout is generated by the vendored ShapeWords shared core; PNG is drawn directly with CanvasKit/Skia.
• seed is honored by browserless/shared-core renders. Use engine: "auto" or engine: "browserless" for reproducible API/MCP output.
• Non-zero seed with forced engine: "browser" is rejected by the Render API because the browser fallback does not use the deterministic shared-core seed path.

Quick Start

Run directly from GitHub:

npx -y github:kirrrr-2423/shapewords-mcp

Or clone locally:

git clone https://github.com/kirrrr-2423/shapewords-mcp.git
cd shapewords-mcp
npm install
npm start

Client Configuration

Use stdio transport in any MCP-compatible client.

{
  "mcpServers": {
    "shapewords": {
      "command": "npx",
      "args": ["-y", "github:kirrrr-2423/shapewords-mcp"],
      "env": {
        "SHAPEWORDS_API_BASE_URL": "https://shapewords.fun"
      }
    }
  }
}

For a local clone:

{
  "mcpServers": {
    "shapewords": {
      "command": "node",
      "args": ["/absolute/path/to/shapewords-mcp/src/index.js"],
      "env": {
        "SHAPEWORDS_API_BASE_URL": "https://shapewords.fun"
      }
    }
  }
}

Environment

Example Prompt

Create a fast SVG word cloud about MCP, universal tools, word cloud generation, AI agents, and ShapeWords. Use the default ShapeWords canvas profile and return the artifact URL.

Example tool input:

{
  "text": "MCP MCP MCP Model Context Protocol word cloud word cloud ShapeWords tools resources prompts stdio server client universal integration connector API render PNG SVG artifact agents automation context protocol schema",
  "locale": "en",
  "format": "svg",
  "width": 800,
  "height": 600,
  "background": "white",
  "quality": "hq",
  "engine": "auto",
  "returnLayout": false,
  "shapeType": "cloud",
  "seed": 12345,
  "palette": ["#7c3aed", "#ddd6fe", "#14b8a6", "#111827"],
  "returnImage": false
}

More Examples

Transparent PNG

{
  "text": "launch launch startup product customers retention growth metrics roadmap",
  "format": "png",
  "engine": "auto",
  "shapeType": "rocket",
  "width": 1200,
  "height": 900,
  "background": "transparent",
  "quality": "hq",
  "returnImage": true
}

Local Skia PNG

{
  "words": [
    { "text": "MCP", "value": 12 },
    { "text": "ShapeWords", "value": 10 },
    { "text": "Skia", "value": 8 },
    { "text": "CanvasKit", "value": 7 },
    { "text": "local", "value": 6 },
    { "text": "renderer", "value": 5 }
  ],
  "format": "png",
  "engine": "skia",
  "shapeType": "cloud",
  "width": 800,
  "height": 600,
  "quality": "sq",
  "seed": 12345
}

JSON Layout

{
  "text": "design system tokens components variants accessibility contrast typography layout",
  "format": "json",
  "engine": "browserless",
  "shapeType": "diamond",
  "returnLayout": true,
  "seed": 7,
  "maxWords": 80
}

Reproducible SVG

{
  "text": "MCP shared core browserless renderer reproducible seed deterministic layout",
  "format": "svg",
  "engine": "browserless",
  "shapeType": "cloud",
  "returnLayout": true,
  "seed": 12345
}

Custom Palette and Font

{
  "text": "research synthesis interview persona journey insight opportunity experiment",
  "format": "svg",
  "shapeType": "book",
  "fontFamily": "Roboto",
  "palette": ["#111827", "#2563eb", "#14b8a6", "#f59e0b"],
  "colorMode": "byFrequency",
  "maxWords": 160
}

Development

npm install
npm run smoke
npm run smoke:skia
npm run inspect

The server uses stdio and writes protocol messages to stdout. Diagnostics are written to stderr.

Notes

• Set returnImage: true in render_word_cloud when the MCP client supports image content and needs hosted-render bytes inline. Local Skia image renders are inline automatically.
• For automation-heavy use, prefer SVG or JSON layout artifacts; request PNG only when the caller needs raster pixels.
• Set seed when the caller needs repeatable SVG/JSON/PNG placement across MCP runs. engine: "skia" is deterministic by default.
• Local Skia PNG output is capped at 40,000,000 pixels after quality scaling to avoid excessive local memory use.
• Local Skia font rendering currently supports bundled Montserrat and OpenDyslexic only. Hosted renders may support more font families.
• The MCP schema currently exposes rendering and style options only. It does not expose ShapeWords UI-only workflows such as the advanced word editor, 2D/3D view switching, CSV/Excel upload, Google Sheets import, or live room controls.
• padding, rotationPreset, rotations, spiralType, and fillMode are exposed so MCP callers can match the main ShapeWords canvas more closely.

See THIRD_PARTY_NOTICES.txt for bundled Font Awesome and font asset notices.