SkillAgentSearch skills...

D2mcp

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

GenerateConvertImprove

Install / Use

/learn @i2y/D2mcp
About this skill

Quality Score

0/100

Supported Platforms

Claude Code
Cursor

README

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

Features

Basic Diagram Operations

  • 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

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

  • 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.24.3 or higher
  • D2 v0.6.7 or higher (included as dependency)
  • For PNG/PDF export (optional):
    • rsvg-convert (from librsvg) or
    • ImageMagick (convert command)

Installation

From Source

# 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

Using Go Install

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

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

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:

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

d2_export

Export a diagram to a specific format:

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

d2_save

Save a diagram to a file:

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

Oracle API Tools

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.

d2_oracle_create

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
}

d2_oracle_set

Set attributes on existing elements:

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

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

d2_oracle_delete

Delete elements from the diagram:

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

d2_oracle_move

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
}

d2_oracle_rename

Rename diagram elements:

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

d2_oracle_get_info

Get information about diagram elements:

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

d2_oracle_serialize

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.

Creating Sequence Diagrams

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

Example Oracle API Workflow

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",
  c

i2y

View profile

View on GitHub
GitHub Stars26
CategoryDevelopment
Updated5d ago
Forks5
i2y/d2mcp

Languages

Go

Security Score

95/100

Audited on Mar 27, 2026

No findings