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 10 tools through the MCP protocol with enhanced descriptions for optimal AI assistant integration, enabling both simple diagram rendering and sophisticated incremental diagram building using the Oracle API.

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

- d2_create- Create new diagrams with optional initial content (unified approach)
- d2_export- Export diagrams to various formats (SVG, PNG, PDF)
- d2_save- Save existing diagrams to files

- 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

- 20 themes- Support for all D2 themes (18 light + 2 dark)

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

- Go 1.24.3 or higher
- D2 v0.6.7 or higher (included as dependency)
- For PNG/PDF export (optional):

- rsvg-convert(from librsvg) or
- ImageMagick (convertcommand)

# Clone the repository git clone https://github.com/i2y/d2mcp.git cd d2mcp # Build the binary make build # Or build for all platforms make build-all

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

# Simple build make build # Run directly make run # Cross-platform builds make build-all

Add to your Claude Desktop configuration file:

macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.jsonLinux:~/.config/Claude/claude_desktop_config.json

For STDIO transport (recommended for Claude Desktop):

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

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

Replace/path/to/d2mcpwith the actual path to your built binary.

# 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

d2mcp now supports multiple transport protocols:

The traditional stdio transport for direct process communication:

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

- -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

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

- -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:

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

Empty diagram (for Oracle API workflow):

{ "id": "my-diagram" }

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

{ "diagramId": "my-diagram", "format": "png" // Options: "svg", "png", "pdf" }

{ "diagramId": "my-diagram", "format": "pdf", "path": "/path/to/output.pdf" // Optional, defaults to temp directory }

The Oracle API tools enable incremental diagram manipulation without regenerating the entire diagram. These tools are ideal for building diagrams step-by-step or making surgical edits.

{ "diagram_id": "my-diagram", "key": "server" // Creates a shape }

{ "diagram_id": "my-diagram", "key": "server -> database" // Creates a connection }

{ "diagram_id": "my-diagram", "key": "server.shape", "value": "cylinder" }

{ "diagram_id": "my-diagram", "key": "server.style.fill", "value": "#f0f0f0" }

{ "diagram_id": "my-diagram", "key": "server" // Deletes the server and its children }

{ "diagram_id": "my-diagram", "key": "server", "new_parent": "network.internal", // Moves server into network.internal "include_descendants": "true" // Also moves child elements }

{ "diagram_id": "my-diagram", "key": "server", "new_name": "web_server" }

{ "diagram_id": "my-diagram", "key": "server", "info_type": "object" // Options: "object", "edge", "children" }

Get the current D2 text representation of the diagram:

{ "diagram_id": "my-diagram" }

Returns the complete D2 text of the diagram including all modifications made through Oracle API.

D2 has built-in support for sequence diagrams. Used2_createwith proper D2 sequence diagram syntax:

{ "id": "api-flow", "content": "shape: sequence_diagram\n\nClient -> Server: HTTP Request\nServer -> Database: Query\nDatabase -> Server: Results\nServer -> Client: HTTP Response\n\n# Add styling\nClient -> Server.\"HTTP Request\": {style.stroke-dash: 3}\nDatabase -> Server.\"Results\": {style.stroke-dash: 3}" }

{ "id": "auth-flow", "content": "shape: sequence_diagram\n\ntitle: Authentication Flow {near: top-center}\n\n# Define actors\nClient: {shape: person}\nAuth Server: {shape: cloud}\nDatabase: {shape: cylinder}\n\n# Interactions\nClient -> Auth Server: Login Request\nAuth Server -> Database: Validate Credentials\nDatabase -> Auth Server: User Data\n\ngroup: Success Case {\n Auth Server -> Client: Access Token\n Client -> Auth Server: API Request + Token\n Auth Server -> Client: API Response\n}\n\ngroup: Failure Case {\n Auth Server -> Client: 401 Unauthorized\n}" }

// 1. Create an empty diagram d2_create({ id: "architecture" }) // 2. Add shapes incrementally d2_oracle_create({ diagram_id: "architecture", key: "web" }) d2_oracle_create({ diagram_id: "architecture", key: "api" }) d2_oracle_create({ diagram_id: "architecture", key: "db" }) // 3. Set properties d2_oracle_set({ diagram_id: "architecture", key: "db.shape", value: "cylinder" }) d2_oracle_set({ diagram_id: "architecture", key: "web.label", value: "Web Server" }) // 4. Create connections d2_oracle_create({ diagram_id: "architecture", key: "web -> api" }) d2_oracle_create({ diagram_id: "architecture", key: "api -> db" }) // 5. Export final result d2_export({ diagramId: "architecture", format: "svg" })

Starting with existing content (unified approach):

// 1. Create diagram with initial content d2_create({ id: "architecture", content: "web -> api -> db\ndb: {shape: cylinder}" }) // 2. Enhance incrementally using Oracle API d2_oracle_set({ diagram_id: "architecture", key: "web.label", value: "Web Server" }) d2_oracle_create({ diagram_id: "architecture", key: "cache" }) d2_oracle_create({ diagram_id: "architecture", key: "api -> cache" }) // 3. Export final result d2_export({ diagramId: "architecture", format: "svg" })

- d2_create: Always use for new diagrams - both empty (for incremental building) and with initial D2 content
- d2_oracle_*: Use for incremental modifications to any diagram created with d2_create
- d2_export: Use to render the final diagram in your desired format

# Run all tests make test # Run with coverage go test -cover ./... # Run specific test go test -v ./internal/presentation/handler

# Format code make fmt # Run linter make lint # Clean build artifacts make clean

- Define entities ininternal/domain/entity
- Add repository interfaces ininternal/domain/repository
- Implement business logic ininternal/usecase
- Add infrastructure implementations
- Create MCP handlers ininternal/presentation/handler
- Wire dependencies incmd/main.go

- cmd/: Application entry point
- internal/domain/: Core business logic and entities
- internal/infrastructure/: External service integrations
- internal/presentation/: MCP protocol handlers
- internal/usecase/: Application business logic

If you get errors when exporting to PNG or PDF formats, install one of these tools:

# Using Homebrew brew install librsvg # or brew install imagemagick

sudo apt-get install librsvg2-bin # or sudo apt-get install imagemagick

Windows: Download and install ImageMagick from the official website.
- Ensure the binary has execute permissions:chmod +x d2mcp
- Check Claude Desktop logs for error messages
- Verify the path in your configuration is absolute

Contributions are welcome! Please feel free to submit a Pull Request.

- Added SSE (Server-Sent Events) transport support for network connectivity
- Added Streamable HTTP transport support for modern bidirectional communication
- New command-line flags for transport configuration
- Support for stateful and stateless modes in Streamable HTTP
- Maintained backward compatibility with stdio transport
- Improved error handling and logging for different transport modes

- Simplified API to unifiedd2_createfor all diagram creation needs
- Enhanced tool descriptions for better AI assistant integration
- Improved Oracle API error handling and validation
- Reduced API surface from 14 to 10 tools
- Breaking Change: Removed d2_render, d2_render_to_file, d2_import, d2_from_text - use d2_create instead

- Addedd2_oracle_serializetool to get current D2 text representation

- Added D2 Oracle API integration for incremental diagram manipulation
- 6 new MCP tools for creating, modifying, and querying diagram elements
- Support for stateful diagram editing sessions

- Initial release with basic D2 diagram operations
- Support for rendering, creating, exporting, and saving diagrams
- 20 built-in themes
- MCP protocol integration

This project is licensed under the MIT License - see theLICENSEfile for details.

Official Context7 MCP server that brings up-to-date, version-specific library documentation and code examples into AI coding prompts.