Doodleworks MCP

Turn any idea (a blog post, an article, an X post) into hand-drawn "Tinku" illustrations that explain the key concepts, right inside your AI host.

<!-- x-release-please-version -->

_{Bring your own image-API key (OpenAI or Gemini) · local stdio server · flip through, regenerate, and download, all in your host's chat.}

Quick start · Add to your host · Using it · Parameters · The viewer · Examples · Configuration · Build from source · How it works

Doodleworks turns a single idea (or a whole blog post, article, or X post) into clean line illustrations that explain its key concepts, one idea per picture. It never draws the topic literally. Instead, it pulls out each concept and reinvents it as a low-tech contraption that Tinku, the app's own character, is physically operating: confident black lines on a pure-white background, with a few neat red/orange/blue handwritten labels.

Ask your AI host for a set of illustrations, and Doodleworks renders them and opens an interactive viewer right in the chat: flip through, regenerate any image you don't like, and download the PNGs.

✨ Highlights

• 🖐️ Hand-drawn, one idea per picture: clean black line art on white with a few red/orange/blue labels; never a literal chart or diagram.
• 🧩 Concepts, not clip art: each key idea becomes a low-tech contraption that Tinku, the app's recurring character, physically operates.
• 🖼️ Interactive viewer in your chat: browse, zoom, regenerate any single image, and download PNGs, inline in supported hosts.
• 🔑 Bring your own key: OpenAI or Gemini. The key stays server-side and is never sent to the viewer or the iframe.
• ⚡ Zero infrastructure: a local stdio server you launch with one npx line. No clone, no build, no database.

🚀 Quick start

No clone and no build required: npx fetches the published doodleworks-mcp package from npm and runs it. You'll need an image-API key to render (none is needed just to install).

1. Get an image key. Use one of:

• OPENAI_API_KEY: OpenAI GPT Image (the default provider)
• GEMINI_API_KEY (or GOOGLE_API_KEY): Gemini 3 Pro Image ("Nano Banana Pro")

New here? Start with OPENAI_API_KEY: it's the default, and every example below was generated with it. Set just one; you don't need both.

2. Add it to your AI host. Drop this into your host's MCP config (Claude Desktop's claude_desktop_config.json shown; see Add it to your AI host for every other host):

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

3. Ask in plain language. Restart the host, then say:

Use doodleworks to create a set of 6 illustrations explaining how a heat pump heats your home, for homeowners, one idea per image.

🔌 Add it to your AI host

Doodleworks is an MCP App: it exposes tools and an interactive UI. Every host below can run the tools, but the inline viewer (the whole point) only renders in hosts that support MCP Apps UI.

Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects):

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "${env:OPENAI_API_KEY}" }
    }
  }
}

Then open Cursor Settings → Tools & Integrations, confirm doodleworks is enabled, and invoke it from Agent chat. Using ${env:OPENAI_API_KEY} keeps the key out of the file (set it in your shell); or paste sk-... directly. The inline viewer requires Cursor 2.6+; older versions run the tools but won't render it.

VS Code uses a servers key (not mcpServers) and can prompt for the key securely. Create .vscode/mcp.json:

{
  "inputs": [
    { "type": "promptString", "id": "openai-api-key", "description": "OpenAI API key", "password": true }
  ],
  "servers": {
    "doodleworks-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "${input:openai-api-key}" }
    }
  }
}

Click Start above the server entry (or run MCP: List Servers), enter the key when prompted, then open Copilot Chat → Agent mode and invoke the tool. The viewer renders inline. Requires VS Code 1.109+ (MCP Apps is in preview).

Goose uses YAML. Edit ~/.config/goose/config.yaml (Windows: %APPDATA%\Block\goose\config\config.yaml):

extensions:
  doodleworks-mcp:
    type: stdio
    name: doodleworks-mcp
    enabled: true
    cmd: npx
    args: ["-y", "doodleworks-mcp"]
    envs:
      OPENAI_API_KEY: "sk-..."
    timeout: 300

Or use the UI: Sidebar → Extensions → Add custom extension (Type: Standard IO; paste npx -y doodleworks-mcp; add the key). Restart Goose after adding. The viewer is Desktop-only and MCP Apps support is experimental.

Open Settings → Developer → Edit Config (or edit ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Save, then fully quit and relaunch Claude Desktop (Cmd+Q, not just closing the window), and the viewer renders inline in the chat. (If an older build shows only a text fallback instead of the gallery, update Claude Desktop.)

claude mcp add --scope project --transport stdio --env OPENAI_API_KEY=sk-... \
  doodleworks -- npx -y doodleworks-mcp

(or commit a project .mcp.json with a top-level mcpServers block). A terminal has no webview, so the interactive viewer does not render here: you'll get tool output, not the gallery. Use a graphical host for the viewer.

Edit ~/.codeium/windsurf/mcp_config.json (Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json; create it if missing):

{
  "mcpServers": {
    "doodleworks-mcp": {
      "command": "npx",
      "args": ["-y", "doodleworks-mcp"],
      "env": { "OPENAI_API_KEY": "sk-..." }
    }
  }
}

Hit Refresh in the Cascade MCP panel (or restart Windsurf). Windsurf runs the tools but does not render MCP Apps UI, so the viewer won't appear inline.

The most dependable way to see the viewer is over Streamable HTTP with a dev host (from a cloned repo):

pnpm start    # watch-build the viewer + serve on http://localhost:3001/mcp

Point the MCP Apps basic-host or the MCPJam inspector at http://localhost:3001/mcp. Both render the viewer correctly and are the recommended way to develop and to verify the gallery.

💬 Using Doodleworks

With the server connected, just ask your host in plain language: the model calls the tools for you and writes each illustration's prompt; you don't have to.

Example prompt (paste into any connected host):

Use doodleworks to create a set of 6 illustrations explaining how a heat pump heats your home, for homeowners, one idea per image.

Prefer to plan first? Invoke the bundled prompt (it surfaces in hosts that show MCP prompts as /mcp__doodleworks-mcp__plan_illustrations):

Run the doodleworks plan_illustrations prompt for topic "how a heat pump heats your home" (audience: homeowners, count: 6), then call create_illustrations with the plan.

In a graphical host (Cursor, VS Code, Claude Desktop, Goose) the viewer opens with the gallery; in Claude Code (terminal) there's no viewer, so you'll get tool output only (a text summary, not the rendered images).

• plan_illustrations (a prompt) turns a topic into a ready-to-render set. Args: topic (required), audience?, count?, spine? (teaching | persuasion | report | product | knowledge-card).
• create_illustrations renders the set (1–10 illustrations, each one paid render) and opens the viewer. Each prompt is a contraption + Tinku's action + a Required text only: block; the server adds the character, the concept engine, and the house style automatically.
• regenerate_illustration re-renders one image (the viewer's Regenerate button).
• get_illustration streams each rendered image into the viewer (app-only; the model never sees it).

See examples/ for ready-to-run payloads (net-ai-stack.json, keep-cool-in-hot-weather.json, tinku-contraptions.json). The planning docs ship as doc://doodleworks/* resources, so any host has them without a separate skill.

🎛️ Parameters

In normal use the model fills these in from your request. You don't write JSON by hand. But you can steer any of them in plain language ("make it a 21:9 hero", "use high quality", "use the glp-00 style", "render at 2k"). Per-call values override the environment defaults.

create_illustrations (set-wide)

Per illustration (each entry inside illustrations[])

plan_illustrations (the planning prompt)

🖼️ The viewer

Once a set renders, the viewer opens in the chat. It's fully interactive:

• Browse: step through with prev/next or the thumbnail strip; the optional 21:9 hero leads, the 16:9 tips follow.
• Streams as it renders: each illustration appears the moment it finishes, so you're never blocked waiting on the whole set.
• Zoom: click any illustration to enlarge it.
• Regenerate: image models are non-deterministic, so one click re-rolls a single illustration in place (no need to redo the whole set).
• Download: save one PNG or the whole set; tick Title on PNG to burn the title into a clean caption band below the artwork.
• Matches your host: it adopts the host's light/dark theme and fonts.

🎨 Examples

Each set below was generated by Doodleworks from a single topic: one idea per panel, each reinvented as a contraption Tinku operates. (Full sets live in assets/style-references/.)

How tirzepatide (a GLP‑1/GIP medication) works, from the first injection through dosing and side effects, turning a dense medication leaflet into nine plain-English pictures. Illustrative examples of the drawing style, not medical advice.

Why nicotine isn't the harmful part, the forms NRT comes in, and how it keeps cravings steady.

Messy sources milled into a linked wiki the model curates: question-and-answer without heavy RAG.

The .NET AI libraries explained: the painful early days, one foundation behind many interfaces, and agents that call tools.

⚙️ Configuration

All configuration is via environment variables (set them in your host's env block). Only an image key is required.

🛠️ Build from source

For contributing, hacking on Tinku, or running the dev viewer inspectors. You need Node.js 22+ and pnpm. No API key is needed to build or test, only to render.

git clone https://github.com/SalZaki/doodleworks-mcp.git
cd doodleworks-mcp
pnpm install
pnpm build      # type-checks + bundles the viewer into dist/mcp-app.html
pnpm test       # offline test suite (~1s, no API calls)

To point a host at your checkout instead of the published package, replace the host config's command with:

"command": "npx",
"args": ["-y", "tsx", "/ABSOLUTE/PATH/doodleworks-mcp/main.ts", "--stdio"]

Replace /ABSOLUTE/PATH/doodleworks-mcp with your clone's real path (pwd in the repo; on Windows use C:\\path\\to\\doodleworks-mcp with doubled backslashes).

See CONTRIBUTING.md for the test-first workflow, the Tinku sync gate, and branch/commit conventions.

🧩 How it works

An MCP App is a tool plus a UI resource. create_illustrations renders the illustrations and is registered with _meta.ui.resourceUri, so the host fetches the ui://doodleworks-mcp/viewer.html resource and renders it in a sandboxed iframe.

To keep your context clean and stay under the MCP per-result size cap, no image bytes go in the tool result: it carries only a setId plus illustration metadata. The server keeps freshly-rendered images in a small in-process LRU (last 8 sets), and the viewer pulls each image via a separate get_illustration call (one image per result). Renders happen in the background, so the call returns immediately and images stream into the viewer as they finish.

host LLM ── create_illustrations(illustrations[]) ─▶ server: render × N  (OpenAI / Gemini, your key)
   model sees: 1-line summary ◀── content (no bytes)         cache.set(setId, …)
   viewer sees: { setId, metadata } ◀── _meta["doodleworks/set"]
   viewer ── get_illustration({ setId, index }) ─▶ one image per result ─▶ iframe gallery

Because images live only in the in-process cache, they survive only as long as the server process (and the last 8 sets). That's the deliberate trade-off of this personal tier: zero infrastructure, no key-handling liability. To persist images or share them across users, that's the signal to move to a hosted tier.

assets/style-references/ is an extensible library: drop in a .png/.jpg/.webp/.gif and it's available immediately as a style reference (it calibrates drawing style only, never the character or text). Set one per-illustration, set-wide, or via DOODLEWORKS_STYLE_REF. See the library README for the full gallery and how it works.

Tinku is the app's own character, defined once in engine.ts as TINKU_CHARACTER: a small solid-black egg-blob worker with two big eyes and mitten-hands, always operating the contraption. Edit that constant to restyle him (and keep references/visual-dna.md in sync via pnpm run check:tinku, enforced by the build).

✅ Status & validation

Personal-tier and experimental, but it works: pnpm install && pnpm build && pnpm test runs green (offline test suite, no API calls), and CI re-runs build + test on Node 22 and 24 with pnpm 10.34.3. The live openai / @google/genai image calls aren't covered by tests; do a live render once after any SDK upgrade.

🤝 Contributing & security

• CONTRIBUTING.md: dev setup, the test-first workflow, and the Tinku sync gate.
• SECURITY.md: report a vulnerability privately.
• CHANGELOG.md: notable changes.

☕ Support this project

Doodleworks is free and maintained in my spare time. If it's useful to you, a coffee helps cover image-API and hosting costs and keeps the updates coming. Thank you.

📄 License

MIT © Salahuddin Zaki. The bundled style-reference images are the project's own artwork; an MIT code license doesn't cover artwork. See the library README.