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.

A hand-drawn Tinku illustration: messy papers fed through a hand-cranked mill come out as a tidy linked wiki.

_{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.

The Doodleworks viewer running in Claude Desktop: a rendered set with prev/next, zoom, regenerate, download, and a thumbnail strip.

_{The interactive viewer in Claude Desktop: browse the set, regenerate any image, and download PNGs (with an optional title burned in).}

✨ 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):

config.json

{
  "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.

[!TIP] The model writes each illustration's prompt for you. You just describe the topic. In a graphical host the viewer opens with the gallery; in a terminal host you'll get tool output only (a text summary, not the rendered images).

🔌 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.

[!TIP] Want the inline viewer? Use Cursor, VS Code, Claude Desktop, or Goose. Claude Code and Windsurf run the tools but can't show the viewer (you'll get tool output instead).

Host	Runs the tools	Shows the viewer	Notes
Cursor (2.6+)	✅	✅	Cleanest experience
VS Code (1.109+)	✅	✅	Copilot agent mode
Goose Desktop (1.19.1+)	✅	✅	Viewer is experimental
Claude Desktop	✅	✅	Fully quit + relaunch after editing config
Claude Code	✅	❌	Terminal has no webview
Windsurf	✅	❌	Tools only
MCPJam / basic-host (dev)	✅	✅	Most reliable way to see the viewer

[!NOTE] Every config below uses the published package (npx -y doodleworks-mcp), so there's no clone and no build. Hacking on your own checkout instead? Swap the command for npx -y tsx /ABSOLUTE/PATH/doodleworks-mcp/main.ts --stdio (see Build from source). Use whichever image key you exported.

Cursor: full viewer (Cursor 2.6+)

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

config.json

{
  "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: full viewer (VS Code 1.109+, GitHub Copilot agent mode)

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

config.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 Desktop: full viewer (Goose Desktop 1.19.1+, experimental)

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

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.

Claude Desktop: full viewer

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):

config.json

{
  "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 Code (terminal): tools only, no viewer ❌

Terminal

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.

Windsurf: tools only, no viewer ❌

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

config.json

{
  "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.

See the viewer reliably (dev inspectors) ✅, needs a local checkout

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

bash

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).

The tools & prompt (reference)

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)

Parameter	Default	What it does
`illustrations`	(required)	The set, in order: 1–10 entries (each is a per-illustration object, below).
`title`	none	A title for the set; shown in the viewer and can be burned onto downloaded PNGs.
`resolution`	`1k`	Size tier: `1k` or `2k` (`2k` is heavier for inline display).
`quality`	`DOODLEWORKS_QUALITY` env, else `low`	OpenAI image quality: `low` / `medium` / `high` / `auto`. Lower is faster and cheaper. Ignored by Gemini.
`styleReference`	`DOODLEWORKS_STYLE_REF` env, else none	Drawing-style reference for the whole set: a library id, a data-URI, or a file inside `assets/style-references/` (tool-supplied paths are sandboxed there; see the note below). Calibrates style only, never the character or text.

Per illustration (each entry inside illustrations[])

Parameter	Default	What it does
`prompt`	(required)	The contraption + Tinku's action + a `Required text only:` block. The server adds the character, the concept engine, and the house style.
`title`	(required)	Short title for this illustration.
`aspect`	`16:9`	`16:9` for a standard panel, or `21:9` for a wider hero illustration.
`archetype`	none	Optional layout aid: `process` / `cycle` / `stack` / `taxonomy` / `matrix` / `timeline` / `decision` / `data-shape` / `summary`.
`styleReference`	the set-wide value	Overrides the set-wide reference for just this illustration (same accepted values and sandbox).

plan_illustrations (the planning prompt)

Parameter	Default	What it does
`topic`	(required)	The topic or source to illustrate.
`audience`	inferred from the topic	Who it's for and what they already know.
`count`	model proposes 4–8	How many illustrations, as an integer (passed as a string in the schema).
`spine`	inferred from the topic	Narrative spine: `teaching` / `persuasion` / `report` / `product` / `knowledge-card`.

[!NOTE] styleReference resolves in order: per-illustration → set-wide → DOODLEWORKS_STYLE_REF env → none. quality resolves set-wide → DOODLEWORKS_QUALITY env → low. With no style reference anywhere, Doodleworks draws from its built-in text-only style guidance. A tool-supplied styleReference is sandboxed: it must be a library id, a data-URI, or a file inside assets/style-references/; only the operator-set DOODLEWORKS_STYLE_REF env may point elsewhere on disk. The viewer's Regenerate button re-renders one illustration and reuses the set's resolution, quality, and style unless you change the 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.

Zooming into a single illustration in the viewer.

_{Zoom view: click any illustration to enlarge it.}

🎨 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/.)

Mounjaro / GLP‑1: a patient explainer

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.

_{At a glance: a once-weekly injection for type‑2 diabetes and weight loss.}

_{Weight loss: turns appetite down so you feel fuller and eat less.}

_{Missed a dose: a track switch: ≤4 days, inject now; more, skip it.}

_{Serious signs: the alarms that mean call for help.}

Nicotine replacement therapy

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

_{The myth vs the harm: nicotine isn't the poison; tar and toxins are.}

_{The forms: patch, gum, lozenge, spray, inhalator.}

_{Holds cravings down: keeps the gauge steady.}

A self‑tending knowledge wiki

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

_{Less code, more knowledge: raw sources milled into a tidy wiki.}

_{Self-tending: the model curates it, hands-off.}

_{It compounds: outputs accumulate over time.}

The .NET AI stack

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

_{The painful beginning: hand-rolled, brittle, ~200 lines.}

_{One foundation: many interfaces from a single socket panel.}

_{Agents with tools: a robot picks tools off a pegboard.}

⚙️ Configuration

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

Variable	Required	Default	What it does
`OPENAI_API_KEY`	one key	none	OpenAI GPT Image (default provider)
`GEMINI_API_KEY` / `GOOGLE_API_KEY`	one key	none	Gemini 3 Pro Image ("Nano Banana Pro")
`DOODLEWORKS_STYLE_REF`	no	none	Default style-reference id/path (library)
`DOODLEWORKS_QUALITY`	no	`low`	`low \| medium \| high \| auto` (raise for more texture)
`DOODLEWORKS_CONCURRENCY`	no	`3`	Illustrations rendered in parallel (safe for OpenAI tier‑1)
`DOODLEWORKS_REQUEST_TIMEOUT_MS`	no	`120000`	Per-image request timeout (ms); a stalled render fails fast instead of pinning a slot
`PORT`	no	`3001`	Port for the dev Streamable HTTP server

[!IMPORTANT] Your image key is read from the server's environment and used server-side only: never placed in a tool result, sent to the viewer, or exposed to the iframe. Keep it in your host's env block or your shell, not in a committed file. (.env is gitignored and is not auto-loaded; the server reads process.env directly.)

🛠️ 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.

bash

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:

json

"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).

[!WARNING] Always run pnpm build before pointing a host at a local checkout. The host serves the prebuilt viewer (dist/mcp-app.html); a missing or stale bundle is the #1 cause of the viewer not showing up. For live iteration use pnpm start (watch-build + restart on edits).

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

🧩 How it works

Architecture: the no-bytes-in-the-result design

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.

Code

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.

Style references & customizing Tinku

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.