Generate, render, and manipulate D2 diagrams with incremental editing capabilities.
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:
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
rsvg-convert
(from librsvg) orconvert
command)# 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.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.
# 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:
./d2mcp -transport=stdio
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:
http://localhost:3000/mcp/sse
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
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:
http://localhost:3000/mcp
Create a new diagram with optional initial content (unified approach):
Empty diagram (for Oracle API workflow):
{
"id": "my-diagram"
}
With initial D2 content:
{
"id": "my-diagram",
"content": "a -> b: Hello\nserver: {shape: cylinder}"
}
Export a diagram to a specific format:
{
"diagramId": "my-diagram",
"format": "png" // Options: "svg", "png", "pdf"
}
Save a diagram to a file:
{
"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.
Create a new shape or connection:
{
"diagram_id": "my-diagram",
"key": "server" // Creates a shape
}
{
"diagram_id": "my-diagram",
"key": "server -> database" // Creates a connection
}
Set attributes on existing elements:
{
"diagram_id": "my-diagram",
"key": "server.shape",
"value": "cylinder"
}
{
"diagram_id": "my-diagram",
"key": "server.style.fill",
"value": "#f0f0f0"
}
Delete elements from the diagram:
{
"diagram_id": "my-diagram",
"key": "server" // Deletes the server and its children
}
Move elements between containers:
{
"diagram_id": "my-diagram",
"key": "server",
"new_parent": "network.internal", // Moves server into network.internal
"include_descendants": "true" // Also moves child elements
}
Rename diagram elements:
{
"diagram_id": "my-diagram",
"key": "server",
"new_name": "web_server"
}
Get information about diagram elements:
{
"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. Use d2_create
with 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}"
}
Example with actors and grouping:
{
"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}"
}
Starting from scratch:
// 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" })
# 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
internal/domain/entity
internal/domain/repository
internal/usecase
internal/presentation/handler
cmd/main.go
If you get errors when exporting to PNG or PDF formats, install one of these tools:
macOS:
# Using Homebrew
brew install librsvg
# or
brew install imagemagick
Ubuntu/Debian:
sudo apt-get install librsvg2-bin
# or
sudo apt-get install imagemagick
Windows: Download and install ImageMagick from the official website.
chmod +x d2mcp
Contributions are welcome! Please feel free to submit a Pull Request.
d2_create
for all diagram creation needsd2_oracle_serialize
tool to get current D2 text representationThis project is licensed under the MIT License - see the LICENSE file for details.
Manage DDEV projects, enabling LLM applications to interact with local development environments through the MCP protocol.
MCP Language Server gives MCP enabled clients access to semantic tools like get definition, references, rename, and diagnostics.
A server for managing sequential development tasks with configurable rules using external .mdc files.
Generate images using OpenAI's DALL-E API.
A test server that demonstrates all features of the MCP protocol, including prompts, tools, resources, and sampling.
MCP Expr-Lang provides a seamless integration between Claude AI and the powerful expr-lang expression evaluation engine.
Access prompt templates managed in an MLflow Prompt Registry. Requires a running MLflow server configured via the MLFLOW_TRACKING_URI environment variable.
Fetches comprehensive information about NuGet packages from the NuGet Gallery, including READMEs, metadata, and search functionality.
A Node.js project demonstrating MCP client and server interactions for tool poisoning attacks, requiring an Anthropic API key.
integration that connects BloodHound with AI through MCP, allowing security professionals to analyze Active Directory attack paths using natural language queries instead of Cypher.