D2

MCP server for the D2 diagram language. Compile, validate, and explore D2 diagrams from any MCP-compatible AI assistant.

Uses the native D2 CLI binary (installed automatically in the Docker image) to compile diagrams into SVG and PNG.

Tools

Tool	Description
compile	D2 source code → SVG/PNG. Supports layout engines, themes, sketch mode, dark themes, multi-board targeting, and more.
validate	Check D2 syntax without rendering. Returns validity status and error details.
list_themes	List all available D2 themes with IDs (light and dark).
list_layouts	List available layout engines (dagre, elk).
list_icons	Browse icons from icons.terrastruct.com by category (AWS, GCP, Azure, K8s, dev, essentials, tech).

Resources

Resource	Description
d2://syntax-reference	Complete D2 language syntax reference in markdown.

Local Development

Prerequisites

• Node.js 22+
• D2 CLI — install from d2lang.com or set the D2_PATH env var to the binary location.
• Icons (optional) — run scripts/download-icons.sh ./icons then set ICONS_DIR=./icons to enable local icon resolution. Without this, icon URLs are passed through to the D2 CLI as-is.

npm install
npm run build
npm start

For development with auto-reload:

npm run dev

The server starts on port 3000 by default (override with PORT env var).

• Health check: GET /health
• MCP endpoint: POST /mcp (Streamable HTTP transport)

Environment Variables

Variable	Default	Description
PORT	3000	HTTP server port
D2_PATH	d2	Path to the D2 CLI binary (resolved via PATH by default)
ICONS_DIR	./icons	Directory containing downloaded SVG icons for local resolution

Deployment (Render)

This project includes a Dockerfile and render.yaml blueprint for one-click deployment to Render. The Docker image automatically installs the D2 CLI binary and downloads all icons at build time.

1. Push this repo to GitHub
2. In Render, create a new Blueprint and connect your repo
3. Render will auto-detect render.yaml and deploy

Or manually create a Web Service with:

• Environment: Docker
• Health Check Path: /health
• Plan: Free

Connecting to the MCP Server

Once deployed, configure your MCP client to connect via Streamable HTTP:

{
  "mcpServers": {
    "d2": {
      "url": "https://your-service.onrender.com/mcp"
    }
  }
}

Replace the URL with your actual Render service URL (or http://localhost:3000/mcp for local).

Compile Tool Options

Parameter	Type	Description
code	string	D2 source code (required)
layout	"dagre" | "elk"	Layout engine (default: dagre)
sketch	boolean	Hand-drawn sketch mode
themeID	integer	Theme ID (see list_themes)
darkThemeID	integer	Dark mode theme ID
pad	integer	Padding in pixels (default: 100)
center	boolean	Center SVG in viewbox
scale	number	Scale factor (default: fit to screen)
target	string	Target board for multi-board diagrams
animateInterval	integer	Animation interval (ms) for multi-board SVGs
noXMLTag	boolean	Omit XML declaration for HTML embedding

License

MIT