@archform/mcp

An MCP server that lets AI assistants render and validate diagrams as code: Mermaid, PlantUML, C4-PlantUML, Graphviz, D2, Structurizr, BPMN and Excalidraw.

It works in Claude Desktop, Claude Code, Cursor and VS Code over stdio, and in ChatGPT developer mode as a remote Streamable HTTP endpoint.

Example

The assistant writes diagram source like this D2:

direction: right
user: User {shape: person}
ai: AI assistant
mcp: Archform MCP
kroki: Kroki {shape: cylinder}
user -> ai: "draw our architecture"
ai -> mcp: render_diagram
mcp -> kroki: diagram source
kroki -> mcp: SVG / PNG
mcp -> ai: image + share link

render_diagram turns it into an image and a share link. The image below is that link:

Try it: once Archform is connected, ask your assistant:

Draw a C4 context diagram of a URL shortener.

Or "Turn schema.prisma into an ER diagram", or "Draw a sequence diagram of our login flow".

Privacy: rendering is done by Kroki. By default, diagram source is sent to the public kroki.io service. If your diagrams describe anything you would not paste into a public website, self-host Kroki and set KROKI_URL.

Tools

All tools are read-only (readOnlyHint: true, openWorldHint: true).

| Tool | Input | Result | | --- | --- | --- | | list_formats | none | Every supported format with aliases, outputs, a docs link and a minimal valid example | | render_diagram | format, source (≤ 100 KB), output (svg default, or png) | SVG as an embedded image/svg+xml resource, or PNG as image content, plus a shareable kroki.io link. Invalid source returns isError: true with the parser message and line | | validate_diagram | format, source | { valid, errors: [{ line?, message }] }. An invalid diagram is a normal result, not a tool error |

Formats

| Format | Aliases | Outputs | | --- | --- | --- | | mermaid | | svg, png | | plantuml | | svg, png | | c4plantuml | | svg, png | | graphviz | dot | svg, png | | d2 | | svg | | structurizr | | svg, png | | bpmn | | svg | | excalidraw | | svg |

Use it locally (stdio)

Requires Node.js 22 or later.

Claude Desktop: add to claude_desktop_config.json:

{
  "mcpServers": {
    "archform": {
      "command": "npx",
      "args": ["-y", "@archform/mcp"]
    }
  }
}

Claude Code:

claude mcp add archform -- npx -y @archform/mcp

Cursor: add to ~/.cursor/mcp.json (or .cursor/mcp.json in a project):

{
  "mcpServers": {
    "archform": { "command": "npx", "args": ["-y", "@archform/mcp"] }
  }
}

VS Code: add to .vscode/mcp.json:

{
  "servers": {
    "archform": { "type": "stdio", "command": "npx", "args": ["-y", "@archform/mcp"] }
  }
}

To use your own Kroki, add "env": { "KROKI_URL": "https://kroki.internal.example.com" } to the server entry.

Run it remotely (Streamable HTTP)

npx -y @archform/mcp --http --port 3000

• POST /mcp: MCP traffic (stateless)
• GET /health: health check

By default the server binds to 127.0.0.1 and rejects requests whose Host or Origin is not localhost (DNS rebinding protection). To expose it publicly, for example for ChatGPT developer mode, bind to all interfaces and name your public hostname:

HOST=0.0.0.0 ALLOWED_HOSTS=mcp.example.com TRUST_PROXY=1 RATE_LIMIT_PER_CLIENT=0 PORT=8080 npx -y @archform/mcp --http

Then add https://mcp.example.com/mcp as a connector in ChatGPT (Settings → Connectors, developer mode) with no authentication. Serve it behind HTTPS.

Limits

The HTTP endpoint limits request bodies to 512 KB and counts tool calls, not HTTP requests. A session's initialize and tools/list requests are not counted.

• Overall: RATE_LIMIT (default 120 per minute) caps tool calls from all clients combined. Size it to what your Kroki backend can handle. The default is polite to the public kroki.io; raise it for a self-hosted Kroki.
• Per client: RATE_LIMIT_PER_CLIENT (default 60 per minute) stops one client from using the whole budget. ChatGPT calls your server from OpenAI's servers, so all ChatGPT users share a handful of IPs, and this limit applies to them together. On a deployment that mainly serves ChatGPT, set RATE_LIMIT_PER_CLIENT=0 (as in the example above) or make it equal to RATE_LIMIT, so ChatGPT users can use the whole overall budget.
• Behind a proxy: most hosts (Render, Fly.io, Railway, Cloud Run) put a proxy in front of your app, so every request seems to come from the proxy's address. Set TRUST_PROXY=1 (the number of proxies in front of the server) so the limiter uses the address your proxy added to X-Forwarded-For. Leave it unset when clients connect directly. Clients can write anything into that header, so it is ignored unless TRUST_PROXY is set.

When a single tool call is over a limit, the model gets a normal tool result with isError: true and a message like "Rate limit reached: … Retry in 42s.", so it can tell the user to wait. An HTTP 429 would show up only as a generic connector failure. Batched or malformed requests over the limit get 429 with Retry-After.

The counters are in memory, so each instance enforces its own limits.

Configuration

| Flag / variable | Default | Meaning | | --- | --- | --- | | --http | off | Serve Streamable HTTP instead of stdio | | --port, PORT | 3000 | HTTP port | | --host, HOST | 127.0.0.1 | HTTP bind address | | ALLOWED_HOSTS | | Comma-separated Host values accepted on a public bind | | RATE_LIMIT | 120 | Tool calls per minute across all clients; 0 disables | | RATE_LIMIT_PER_CLIENT | 60 | Tool calls per minute per client IP; 0 disables | | TRUST_PROXY | 0 | Number of reverse proxies whose X-Forwarded-For entries are trusted (true = 1) | | KROKI_URL | https://kroki.io | Kroki server used for rendering and share links |

Self-hosting Kroki

Kroki ships as Docker images. The core image covers PlantUML, C4-PlantUML, Graphviz, D2 and Structurizr; Mermaid, BPMN and Excalidraw each need a companion container:

# docker-compose.yml
services:
  kroki:
    image: yuzutech/kroki
    ports: ["8000:8000"]
    environment:
      KROKI_MERMAID_HOST: mermaid
      KROKI_BPMN_HOST: bpmn
      KROKI_EXCALIDRAW_HOST: excalidraw
  mermaid:
    image: yuzutech/kroki-mermaid
  bpmn:
    image: yuzutech/kroki-bpmn
  excalidraw:
    image: yuzutech/kroki-excalidraw

docker compose up -d
KROKI_URL=http://localhost:8000 npx -y @archform/mcp

Shareable links then point at your Kroki instance, so they only open for people who can reach it. See the Kroki installation docs for details.

Development

pnpm install
pnpm test                      # unit + in-process integration tests (Kroki stubbed)
KROKI_LIVE=1 pnpm test         # also run the live tests against KROKI_URL
pnpm build
npx @modelcontextprotocol/inspector node dist/index.js           # stdio
node dist/index.js --http      # then point the Inspector at http://127.0.0.1:3000/mcp

License

MIT