d2mcp

D2MCP is a server that exposes D2 diagram functionality over the MCP protocol. It supports creating diagrams, exporting them to SVG, PNG, or PDF, and saving diagrams to files. In addition, it provides a robust Oracle API for incremental editing, allowing you to create shapes and connections step-by-step, update element attributes, move elements between containers, rename items, query information, and serialize the current diagram back to D2 syntax. With the Oracle API, you can iteratively build complex diagrams from conversational input, making it ideal for turning requirements and discussions into up-to-date architecture or flow diagrams. The server ships with a broad set of themes (20 in total) and is designed to work with clients like Claude by accepting and returning structured JSON messages that describe diagrams and operations.

To use D2MCP, connect to the server via one of the supported MCP transports (stdio, SSE, or streamable HTTP). For Claude Desktop or similar integrations, you typically configure the MCP host in your client’s settings and send tool requests as JSON payloads. The server exposes tools such as d2_create for initializing diagrams, d2_export for producing export formats, d2_save for persisting diagrams, and the Oracle API tools (d2_oracle_create, d2_oracle_set, d2_oracle_delete, d2_oracle_move, d2_oracle_rename, d2_oracle_get_info, d2_oracle_serialize) for incremental editing. You can start with a simple workflow that creates a diagram, adds shapes and connections via the Oracle API, and gradually exports or saves as your diagram evolves.

If you’re integrating programmatically, you’ll typically send JSON payloads describing the operation, such as creating a diagram with an initial content string, or operating on specific diagram elements through the Oracle API, then request a serialization to obtain the current D2 text for storage or further processing.

Prerequisites:

• Go 1.24.3 or higher
• D2 tool v0.6.7 or higher (included as dependency in the project)
• Optional for PNG/PDF export: librsvg (rsvg-convert) or ImageMagick (convert) installed on the system

Install from source:

# Clone the repository
git clone https://github.com/i2y/d2mcp.git
cd d2mcp

# Build the binary
make build

# (Optional) Build for all platforms
make build-all

Install via Go install:

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

Running locally (example):

# Run the MCP server (stdio transport) after building
./d2mcp -transport=stdio

If you prefer using a prebuilt binary via a package manager or a container, follow the project’s standard release workflow and point your MCP configuration to the built binary path.

Tips and common considerations:

• Transport choice matters: stdio is best for direct process communication with local clients, while SSE or streamable HTTP enables remote integration. Update the mcp_config accordingly with the desired command-line flags.
• For export formats (SVG, PNG, PDF), ensure the optional tools (rsvg-convert or ImageMagick) are available if you plan to generate PNG/PDF outputs.
• The Oracle API enables incremental editing, which is ideal for building diagrams step-by-step. Use d2_oracle_serialize to retrieve the current D2 text after a series of modifications.
• Themes: The server includes 20 D2 themes. When exporting or rendering, you can apply a theme by specifying the appropriate diagram or rendering options within your client workflow.
• Environment variables: You can provide runtime hints or configuration overrides via environment variables in your MCP config. Use descriptive names like D2MCP_CONFIG_HINT to aid client tooling.
• If you encounter transport-related issues, verify network accessibility for SSE/streamable transports and ensure the port bindings (e.g., :3000) are reachable from your client.