D2 Mcp Rs

d2-mcp-rs

[](https://github.com/Stranmor/d2-mcp-rs/actions/workflows/ci.yml) [](LICENSE) [](rust-toolchain.toml) [](https://modelcontextprotocol.io/) [](https://d2lang.com/)

Render, validate, and format D2 diagrams from MCP clients without giving agents arbitrary shell access.

d2-mcp-rs is a small Rust MCP server that wraps the official D2 CLI with typed tools, bounded file output, structured artifact reports, and default-off remote asset fetching. It is built for AI agents that need to create architecture diagrams repeatedly, safely, and in a form humans can open immediately.

What It Gives Agents

| Tool | Purpose | Side effect | | --- | --- | --- | | d2_status | Reports D2 availability, server limits, supported output formats, and safety policy. | None | | d2_layouts | Lists layout engines available in the configured D2 CLI. | None | | d2_themes | Lists themes available in the configured D2 CLI. | None | | d2_validate | Validates D2 source text and returns structured diagnostics. | None | | d2_format | Formats D2 source text and returns the formatted source. | None | | d2_render | Renders D2 source text to SVG or PNG and returns output path, hashes, bytes, diagnostics, and optional inline SVG. | Writes only inside D2_MCP_WORKDIR |

Why This Exists

AI agents can draft diagrams, but raw shell execution is the wrong interface for repeated diagram work. Agents need a narrow contract:

• no pass-through shell command tool;
• JSON schemas for every input and output;
• one configured output directory;
• path traversal rejection;
• source and render size limits;
• process timeouts;
• remote http:// and https:// assets blocked unless explicitly requested;
• real D2 rendering behavior because the official d2 binary remains the renderer.

Quick Start

Install D2 first:

curl -fsSL https://d2lang.com/install.sh | sh -s --
d2 --version

Install the MCP server from GitHub:

cargo install --git https://github.com/Stranmor/d2-mcp-rs.git d2-mcp

Create an output directory:

mkdir -p "$HOME/d2-mcp-output"

Add it to your MCP client:

{
  "mcpServers": {
    "d2": {
      "command": "d2-mcp",
      "env": {
        "D2_MCP_WORKDIR": "/home/you/d2-mcp-output"
      }
    }
  }
}

Then ask your MCP client to render a diagram:

{
  "source": "client -> d2_mcp -> d2_cli -> svg",
  "format": "svg",
  "output_path": "architecture/current.svg",
  "overwrite": true,
  "inline_svg": true
}

See [client configuration examples](docs/client-configs.md) for absolute-path setups.

Example Diagram Source

user: User request
agent: MCP client
server: d2-mcp-rs
d2: Official D2 CLI
artifact: SVG or PNG artifact

user -> agent: asks for a diagram
agent -> server: calls d2_validate / d2_render
server -> d2: invokes bounded D2 command
d2 -> server: rendered artifact
server -> agent: structured report
agent -> user: shares final diagram

Tool Details

The main tool docs are in [docs/tools.md](docs/tools.md). Short version:

• use d2_status before rendering to confirm the D2 binary and limits;
• use d2_layouts and d2_themes to choose valid render options without shell access;
• use d2_validate before a final render when the source came from a model;
• use d2_format when storing generated D2 source;
• use d2_render for final SVG/PNG output.

Configuration

| Variable | Default | Purpose | | --- | --- | --- | | D2_MCP_D2_BIN | d2 | D2 executable path or command name. | | D2_MCP_WORKDIR | current process directory | The only directory where rendered files may be written. | | D2_MCP_MAX_SOURCE_BYTES | 1048576 | Maximum D2 source input size. | | D2_MCP_MAX_RENDER_BYTES | 16777216 | Maximum rendered artifact size. |

output_path in d2_render must be relative. Absolute paths and .. components are rejected.

Security Model

d2-mcp-rs narrows what an MCP client can do. It does not claim to sandbox the D2 renderer itself.

The server:

• accepts D2 source text from MCP calls;
• never exposes a generic shell command;
• never reads arbitrary user files as a tool feature;
• writes rendered artifacts only inside D2_MCP_WORKDIR;
• rejects absolute paths and parent-directory traversal;
• blocks remote assets by default;
• invokes the configured D2 binary with explicit arguments;
• kills the D2 process when the timeout is exceeded.

If you intentionally need remote icons or images:

{
  "allow_remote_assets": true
}

Use that only when the workspace policy allows network fetches during rendering. See [docs/security-model.md](docs/security-model.md) for the full boundary.

Development

cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test

The integration smoke test starts the MCP server in memory, lists the tools, checks structured output schemas, calls read-only discovery tools, renders a real SVG when D2 is installed, and verifies path traversal rejection.

Project Status

The current goal is a dependable, small, agent-safe D2 MCP server rather than a full diagram management system. File-reading tools, project-wide diagram discovery, and diagram asset libraries should be added only as separate narrowly scoped tools with their own path policy.

License

MIT

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Stranmor
• Source: Stranmor/d2-mcp-rs
• License: MIT
• Homepage: https://github.com/Stranmor/d2-mcp-rs

Install and usage instructions live in the source repository linked above.