D2 MCP Server

D2 MCP Server

A Model Context Protocol (MCP) server that provides D2 diagram generation and manipulation capabilities.

D2 is a modern diagram scripting language that turns text to diagrams. This MCP server allows AI assistants like Claude to create, render, export, and save D2 diagrams programmatically.

The server provides 16 MCP tools for complete-source authoring, validation, rendering, embedded D2 guidance, and incremental Oracle editing.

With the new Oracle API integration, AI assistants can now build and modify diagrams incrementally, making it perfect for:

• Converting conversations into architecture diagrams
• Building flowcharts step-by-step as requirements are discussed
• Creating entity relationship diagrams from database schemas
• Generating system diagrams from code analysis
• Refining diagrams based on user feedback without starting over

Features

Source-First Diagram Operations

• d2_create - Create diagrams from complete D2 source or start empty
• d2_get_source - Retrieve the canonical source, including Oracle edits
• d2_update_source - Validate then atomically replace complete source
• d2_format - Format valid source without storing it
• d2_validate - Validate raw or stored source and suggest conservative repairs
• d2_export - Export with bundled D2 v0.9 renderers (SVG, PNG, PDF, PPTX, GIF, ASCII)
• d2_save - Save an export inside a configured workspace root
• d2_help - Search or retrieve embedded D2 v0.9 guidance
• d2_capabilities - List the versioned capability catalog

Oracle API for Incremental Editing

• d2_oracle_create - Create shapes and connections incrementally
• d2_oracle_set - Set attributes on existing elements
• d2_oracle_delete - Delete specific elements from diagrams
• d2_oracle_move - Move shapes between containers
• d2_oracle_rename - Rename diagram elements
• d2_oracle_get_info - Get information about shapes, connections, or containers
• d2_oracle_serialize - Get the current D2 text representation of the diagram

Additional Features

• Bundled layouts - Dagre, ELK, and TALA
• Typed rendering - Layout, theme overrides, bundled fonts, scale, padding, sketch, animation, board selection, and bounded output options
• 20 themes - Support for all D2 themes (18 light + 2 dark)

Project Structure

d2mcp/

├── cmd/ # Application entry point ├── internal/ │ ├── domain/ # Business entities and interfaces │ │ ├── entity/ # Domain entities │ │ └── repository/ # Repository interfaces │ ├── usecase/ # Business logic │ ├── infrastructure/ # External implementations │ │ ├── d2/ # D2 library integration │ │ └── mcp/ # MCP server implementation │ └── presentation/ # MCP handlers │ └── handler/ # Tool handlers └── pkg/ # Public packages

Prerequisites

• Go 1.27 or higher
• D2 v0.9.0 (included as a Go dependency)

All export formats use bundled Go renderers; no rsvg-convert, ImageMagick, or Chromium installation is required.

The embedded capability catalog is based on the official D2 language tour, D2 API documentation, and D2 v0.9.0 release.

Installation

From Source

# Clone the repository

git clone https://github.com/recursivefunctions/d2mcp.git cd d2mcp

Build the binary

make build

Or build for all platforms

make build-all

Using Go Install

go install github.com/recursivefunctions/d2mcp/cmd@latest

Using Docker

docker run --rm -i \

--mount type=bind,src="$PWD",dst=/workspace \ ghcr.io/recursivefunctions/d2mcp:0.5.0

The image defaults to STDIO transport and confines local imports, assets, and exports to the mounted /workspace directory. The container runs as a non-root user, so the mounted directory must be writable by that user when saving exports.

MCP Registry

Release tags publish the server as io.github.RecursiveFunctions/d2mcp in the official MCP Registry. Registry publication and editor-gallery indexing are separate, so a newly published version might not appear immediately in an editor's search results.

Compatible clients can also use the portable .mcp.json configuration in this repository. It requires Docker and mounts the current workspace at /workspace.

Editor Integrations

Client configurations are generated from server.json, so they always use the same immutable container version.

Run make generate-adapters after changing release metadata. CI runs make verify-adapters and rejects stale client configurations.

Building

# Simple build

make build

Run directly

make run

Cross-platform builds

make build-all

Usage

With Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

For STDIO transport (recommended for Claude Desktop):

{

"mcpServers": { "d2mcp": { "command": "/path/to/d2mcp", "args": ["-transport=stdio"] } } }

For SSE transport:

{

"mcpServers": { "d2mcp": { "command": "/path/to/d2mcp", "args": ["-transport=sse", "-addr=:3000"] } } }

Replace /path/to/d2mcp with the actual path to your built binary.

Standalone

# Run the MCP server (stdio transport)

./d2mcp -transport=stdio

Run with SSE transport (default)

./d2mcp

or explicitly

./d2mcp -transport=sse

Run with Streamable HTTP transport

./d2mcp -transport=streamable

Transport Options

d2mcp now supports multiple transport protocols:

STDIO Transport

The traditional stdio transport for direct process communication:

./d2mcp -transport=stdio

SSE Transport (Server-Sent Events)

HTTP-based transport that allows network connectivity:

# Basic SSE mode (defaults to :3000)

./d2mcp -transport=sse

Custom configuration

./d2mcp -transport=sse \ -addr=:8080 \ -base-url=http://localhost:8080 \ -base-path=/mcp \ -keep-alive=30

SSE Configuration Options:

• -addr: Address to listen on (default: ":3000")
• -base-url: Base URL for SSE endpoints (auto-generated if not specified)
• -base-path: Base path for SSE endpoints (default: "/mcp")
• -keep-alive: Keep-alive interval in seconds (default: 30)

SSE Endpoints: When running in SSE mode, the following endpoints are available:

• SSE stream: http://localhost:3000/mcp/sse
• Message endpoint: http://localhost:3000/mcp/message

Streamable HTTP Transport

The modern HTTP-based transport that simplifies bidirectional communication:

# Basic Streamable HTTP mode

./d2mcp -transport=streamable

Custom configuration

./d2mcp -transport=streamable \ -addr=:8080 \ -endpoint-path=/mcp \ -heartbeat-interval=30 \ -stateless

Streamable HTTP Configuration Options:

• -addr: Address to listen on (default: ":3000")
• -endpoint-path: Endpoint path for Streamable HTTP (default: "/mcp")
• -heartbeat-interval: Heartbeat interval in seconds (default: 30)
• -stateless: Enable stateless mode (default: false)

Streamable HTTP Endpoint: When running in Streamable HTTP mode, a single endpoint handles all communication:

• Endpoint: http://localhost:3000/mcp

Workspace and Asset Security

The server confines imports, local images, and saved files to named workspace roots. The default root is the server's current working directory.

./d2mcp -transport=stdio \

-workspace-root=docs=/workspace/docs \ -workspace-root=diagrams=/workspace/diagrams \ -remote-asset-max-bytes=10485760 \ -remote-asset-timeout=30s

-workspace-root is repeatable. Local path traversal and symlink escapes are rejected. Remote assets require HTTPS and are subject to DNS/IP, redirect, timeout, MIME, and response-size checks; loopback and private-network destinations are rejected.

Tools

d2_create

Create a new diagram with optional initial content (unified approach):

Empty diagram (for Oracle API workflow):

{

"id": "my-diagram" }

With initial D2 content and a named workspace for imports/assets:

{

"id": "my-diagram", "content": "a -> b: Hello\nserver: {shape: cylinder}", "workspace_root": "diagrams" }

d2_export

Export a diagram using a bundled renderer and layout engine:

{

"diagramId": "my-diagram", "format": "png", "layout": "tala", "themeId": 200, "scale": 1.5, "maxPixels": 33554432 }

Formats are svg, png, pdf, pptx, gif, and ascii (txt is an alias). Layouts are dagre, elk, and tala. Typed options cover engine spacing, themes and overrides, bundled fonts, padding, scale, sketch mode, animation, board selection, and resource limits.

PDF, PPTX, GIF, and optionally animated SVG compose bounded descendant boards. PNG and ASCII produce one board; use boardPath to select one from a composition.

d2_save

Save a diagram inside a configured workspace root:

{

"diagramId": "my-diagram", "format": "pdf", "workspace_root": "diagrams", "path": "exports/output.pdf" }

If path is omitted, output is written below d2mcp_output/ in the selected root.

d2_validate

Validate raw D2 source or the current source of a stored diagram. Supply exactly one input:

{

"content": "a: {\n b" }

{

"diagram_id": "my-diagram" }

Invalid D2 returns a successful structured result with valid: false and compiler diagnostics. Simple, unambiguous terminator errors may also include repaired_content; validation never modifies a stored diagram.

d2_get_source and d2_update_source

Complete D2 source is canonical, so every bundled v0.9 language feature can be authored without waiting for a specialized structured tool.

{"diagram_id": "my-diagram"}

{

"diagram_id": "my-diagram", "content": "direction: right\nclient -> api -> database" }

Updates compile first and replace atomically. Invalid drafts return structured diagnostics and leave stored source unchanged.

d2_format

{"content": "api:{db}"}

Returns formatted source without creating or changing a diagram.

d2_help and d2_capabilities

{"query": "sequence diagrams", "limit": 5}

d2_help searches the embedded v0.9.0 reference or returns an exact topic by ID. d2_capabilities lists its categories and MCP resource URIs. Embedded resources cover the core language, connections, reusable definitions, visuals, rich text, structured/sequence/grid diagrams, composition, layouts, and exports.

Oracle API Tools

The Ora