sysketch MCP

Why sysketch

When you ask an AI assistant for a diagram, it usually writes every line, box and coordinate by hand. That is slow, uses up a lot of your AI usage, and every diagram looks different.

With sysketch, the AI writes a short description of your system and sysketch draws it.

• Faster and cheaper: 18x fewer AI output tokens and about 9x faster than having the AI draw the image itself (benchmark).
• Consistent: every diagram shares the same polished style, icons and layout rules.
• Easy to change: "add a cache in front of the database" is a one-line edit, not a redraw.
• Works anywhere: SVG or PNG files that look the same in GitHub, Notion, Figma, docs and slides.

Get started

sysketch connects to AI assistants through MCP, the standard way to give them new tools. Pick the option that matches how you use AI.

In your AI chat (nothing to install)

Any web-based AI chat that supports custom connectors (also called MCP servers) can use sysketch, including Claude, ChatGPT and Perplexity. Add a custom connector with this URL. No account or sign-in is needed.

https://sysketch.vercel.app/mcp

• Claude (web, desktop and mobile): Settings → Connectors → Add custom connector.
• ChatGPT: turn on Developer mode (Settings → Apps & Connectors → Advanced), then create a connector with the URL and no authentication. Developer mode is available on paid plans.
• Perplexity and other chats: look for custom connectors or MCP in the settings.

Then ask for a diagram:

Use sysketch to draw a ride-sharing app: rider and driver apps, an API gateway, a matching service, a location service and a trip database.

In Claude and ChatGPT the diagram opens right in the chat, with zoom, fullscreen and PNG/SVG download buttons. Other chats show a preview with links to the full PNG and SVG. To change it, just ask ("add a payment service"). Product names like stripe, kafka or postgres show the product's official logo (from Simple Icons). Nothing is stored on the server: each link contains the diagram's description, so anyone with the link can see that diagram. The AWS, Azure and Google Cloud icon packs and your own company's logos need the local version below. Setup and the connector's limits are in the hosted server guide.

In Claude Code, Cursor and other coding assistants

This runs sysketch on your computer and saves diagrams straight into your project. You need Node.js 20 or newer.

Claude Code: run this once in your terminal:

claude mcp add sysketch -- npx -y sysketch-mcp

Claude Desktop, Cursor and other assistants: add this to the assistant's MCP settings, then restart it:

{
  "mcpServers": {
    "sysketch": { "command": "npx", "args": ["-y", "sysketch-mcp"] }
  }
}

Claude Desktop saves diagrams in a sysketch folder in your home folder. To use another folder, add "--dir", "/path/to/folder" after "sysketch-mcp".

Then ask the same way, for example "use sysketch to draw this repo's architecture as a PNG". The diagram is saved in your project as an image, along with its short description, so you can ask for changes later. This version also supports official logos.

From the command line

You need Node.js 20 or newer. Write a description of your system in a file called diagram.yaml:

title: URL Shortener
groups:
  Backend: [api, cache, db]
edges:
  - client > lb | POST /shorten
  - lb > api
  - api > cache
  - api > db

Then draw it:

npx sysketch render diagram.yaml

That creates diagram.svg:

Add --png for an image file, or --theme graphite for a different look.

Writing a diagram

A diagram has three parts. Only edges is required.

Part	What it does	Example
edges	Arrows between parts of your system	client > lb > api | GET /home
nodes	Optional names, icons and notes	api: server | API Server | 3 replicas
groups	Optional boxes around related parts	Backend: [api, cache, db]

Common names like client, api, db, cache, queue, redis, kafka, s3 or stripe pick the right icon automatically. You can also use dashed (..>), two-way (<>), thick (=>) and plain (--) arrows, colors, groups inside groups for cloud networks, a numbered step legend, and type: sequence for sequence diagrams. Everything is in the spec guide.

If something is wrong, sysketch says how to fix it: unknown node "databse". Did you mean: database?

Themes

Sketch (default)	Graphite	Blueprint	Midnight	Classic

Pick one with theme: graphite in your diagram file, or ask your assistant for "the blueprint theme". Every diagram includes 61 original icons that adapt to the theme.

Examples

Click any diagram to see the description that produced it. More in examples/.

This is the beginning of the README. Read the rest at the original. Read the full README ↗