noddle draw MCP server
Lets an AI agent (Claude Code, Claude Desktop, or any MCP client) work on a board
alongside you: read, create and edit boards, browse version history, and comment like
any other collaborator.
noddle draw is anonymous. There are no accounts and no tokens. A board id (12 hex
chars) or a board URL is the capability. The agent can open any board you give it, and
anyone holding the link of a board the agent creates can open it too. The agent signs its
comments and version snapshots with NODDLE_AGENT_NAME.
- Stdlib-only Python β₯ 3.9 (
urllib + json), so there is nothing to install.
- stdio transport: one JSON-RPC 2.0 message per line. stdout carries only protocol
messages, and logs go to stderr.
- MCP protocol, dual-era:
- 2026-07-28 (modern, stateless): every request carries
_meta["io.modelcontextprotocol/protocolVersion"] + clientCapabilities. The server
implements server/discover, and sets resultType and
_meta["io.modelcontextprotocol/serverInfo"] on every result, plus ttlMs/cacheScope
on list/read results. An unsupported version returns -32022 UnsupportedProtocolVersion.
- Legacy
initialize handshake: 2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05. The
server answers with the client's version when it supports it, and otherwise with
2025-11-25. ping works in this mode. JSON-RPC batches are accepted only for
2025-03-26, the only revision that allowed them.
1. Register
Claude Code (from the repo root; an absolute script path is more robust):
claude mcp add noddle -- python3 mcp/noddle_mcp.py
claude mcp add noddle --env NODDLE_BASE_URL=http://127.0.0.1:8000 -- python3 mcp/noddle_mcp.py
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json)
or a project .mcp.json use the same shape:
{
"mcpServers": {
"noddle": {
"command": "python3",
"args": ["/absolute/path/to/noddle-draw/mcp/noddle_mcp.py"],
"env": { "NODDLE_BASE_URL": "https://draw.noddle.dev" }
}
}
}
MCP Bundle (one-click install in Claude Desktop and other MCPB clients): download
noddle-draw.mcpb from the latest mcpb-v* release
and open it. It needs only Python 3.10+ (standard library, no install step).
From a checkout (pyproject.toml here):
uvx --from ./mcp noddle-draw-mcp
The server is listed in the official MCP Registry
as dev.noddle/draw (see Releasing).
| Env | Default | |
|---|
NODDLE_BASE_URL | https://draw.noddle.dev | http(s) origin of the noddle draw instance. A non-http(s) value exits with code 2 |
NODDLE_AGENT_NAME | MCP agent | display name on comments and version history (max 40 chars) |
NODDLE_TIMEOUT | 30 | seconds per board API call |
NODDLE_AI_TIMEOUT | 180 | seconds for generate_diagram |
NODDLE_AI_PROVIDER | β | optional BYOK for generate_diagram: claude, openai, gemini, openrouter or custom |
NODDLE_AI_KEY | β | your AI provider key. It is sent only to NODDLE_BASE_URL, as the same X-AI-* headers the web app uses, and never stored. Unset means the instance's shared pool is used, if it has one |
NODDLE_AI_MODEL | β | optional model override |
NODDLE_AI_BASE | β | OpenAI-compatible base URL (provider custom only) |
CLI: --help, --version, --list-tools (prints the tool definitions as JSON).
Exit codes: 0 when stdin closes (normal shutdown), 2 for bad configuration.
Every tool returns structuredContent that conforms to its outputSchema, plus the same
JSON as a text block. Board tools also return a resource_link to noddle://board/{id}
(revisions β₯ 2025-06-18). Wherever a tool takes doc_id, you can pass either the 12-hex
id or the board URL ({base}/d/{id} or /embed/{id}). A URL on a different origin than
NODDLE_BASE_URL is refused.
| Tool | readOnly | destructive | idempotent | openWorld | What it does |
|---|
get_board | β | | | β | Name, url, my_role (editor/viewer), updated_at, page summary and diagram JSON. Optional page_id and include_svg |
create_board | β | β | β | β | New board, with optional diagram JSON. Anyone with its url can edit it |
update_board | β | β | β | β | Replace the WHOLE diagram (fetch β edit β send back). A version snapshot is kept. expected_updated_at turns a concurrent edit into a conflict error instead of an overwrite |
rename_board | β | β | β | β | Rename |
list_versions | β | | | β | Version-history snapshots, newest first |
get_version | β | | | β | One snapshot's diagram. To restore it, pass it to update_board |
list_comments | β | | | β | Comment threads |
add_comment | β | β | β | β | Pin to ONE of node_id / edge_id / parent_id (reply) / point x,y (+ page_id). Works on view-only links too |
generate_diagram | β | | | β | Turns prose or Mermaid into diagram JSON through the instance's AI (your BYOK key or its shared pool). It saves nothing, so pass the result to create_board/update_board |
There is deliberately no list_boards and no delete: the API has neither. Link access
is not discovery, and an anonymous board has no owner who could be trusted to delete it.
Writes to a board whose link is view-only fail with a 403 tool error.
Diagram payloads are pass-through. The server checks only the envelope
({pages:[{id,nodes,edges}]} or legacy {nodes,edges}, with string ids). Node and edge
fields are forwarded untouched, so new editor fields (e.g. the freedraw kind with
points, or curved routing) work without a server update. See DiagramNode /
DiagramEdge in contracts/openapi.yaml.
Errors:
- Bad arguments, API failures (400/403/404/413/422/429/503) and conflicts come back as
isError: true tool results that the model can act on.
- Protocol errors use standard JSON-RPC codes: unknown tool or invalid params
-32602, unknown method -32601, malformed JSON -32700, invalid request -32600.
3. Resources & prompts
- Resources:
resources/list lists the boards this session has created, read or
edited, as noddle://board/{id} (application/json, lastModified). It starts empty,
because the API has no listing. resources/templates/list exposes
noddle://board/{doc_id}, so a client can read any board by id. resources/read
returns the same JSON as get_board. An unknown board returns -32602.
- Prompts:
design_board(topic, notes?): generate β sanity-check β create_board β reply with
the url.
review_board(doc_id): embeds the board as a resource and asks for a critique posted
as anchored comments.
4. Example (Claude Code)
> Create a board "Payment flow" with Client β API Gateway β Payment Service β Database,
then comment on the Database node reminding the team to review indexes.
Claude: generate_diagram(text="Client -> API Gateway -> Payment Service -> Database")
β create_board(name="Payment flow", diagram=β¦)
β add_comment(doc_id, body="Please review indexes for the payments table", node_id="db")
β returns https://draw.noddle.dev/d/{id}
Comments reach an open board in realtime. A diagram written with update_board shows up
when the board is reloaded.
5. Tests
test_noddle_mcp.py runs the real server over stdio against a fake in-process REST
backend. It covers version negotiation (modern and legacy), schema validity, read and
write tools, board-URL ids, view-only links, resources, prompts, BYOK header forwarding
and error paths. It also asserts that stdout carries only JSON-RPC, that no request ever
carries an Authorization header, and that a BYOK key never leaks into output or logs.
Releasing
mcp/server.json is the registry listing (dev.noddle/draw); it points at the MCP Bundle
attached to a GitHub release. The dev.noddle/* namespace is verified over HTTP: noddle.dev
serves the publisher's ed25519 public key at /.well-known/mcp-registry-auth.
- Bump the version everywhere, all equal:
__version__ in noddle_mcp.py, version in
mcpb/manifest.json, version in pyproject.toml, and version in server.json.
Registry versions are immutable; a metadata-only fix uses a suffix such as 1.0.0-1.
- Build the bundle:
mcp/build_mcpb.sh β mcp/dist/noddle-draw.mcpb (prints its SHA-256).
- Create the release with that exact file:
gh release create mcpb-v<version> mcp/dist/noddle-draw.mcpb --title "MCP server <version>".
- In
server.json, set the package identifier to the release download URL and
fileSha256 to the printed hash, then publish with the namespace key holder's
mcp-publisher login http --domain noddle.dev --private-key β¦ and
mcp-publisher publish mcp/server.json.
Notes
update_board keeps the stored SVG preview. The preview refreshes on the next save in
the editor.
- Cross-origin HTTP redirects are refused, so a BYOK key is never forwarded to another
host. A BYOK key over plain
http to a non-loopback host logs a warning.
generate_diagram sends text to an AI provider. Never pass customer PII, credentials or
account numbers.