Diagram Bridge MCP Server

A comprehensive MCP server that bridges the gap between LLMs and diagram creation through three powerful, independent tools: intelligent format selection, format-specific instruction generation, and professional diagram rendering (using kroki server). Each tool can be used standalone or combined in sequence for complete diagram workflows - from choosing the right format to generating the final image.

Supported Formats: Mermaid, PlantUML, C4 Model, D2, GraphViz, BPMN, Structurizr, Excalidraw, Vega-Lite

Quick Start

1. Prerequisites:

   • Node.js 18.0 or higher
   • Docker and Docker Compose

2. Install and build:

git clone git@github.com:tohachan/diagram-bridge-mcp.git
cd diagram-bridge-mcp
npm install && npm run build

3. Configure ports (optional):

# Copy and edit environment file to customize ports
cp .env.example .env
# Edit .env to set PORT and KROKI_PORT as needed

# Or set environment variables directly:
export PORT=4000        # MCP Server port (default: 3000)
export KROKI_PORT=9000  # Kroki service port (default: 8000)

4. Start services:

# Option 1: Interactive port configuration
./scripts/start-with-ports.sh

# Option 2: Default ports (3000 for MCP, 8000 for Kroki)
docker-compose up --build

# Option 3: Custom ports via environment variables
PORT=4000 KROKI_PORT=9000 docker-compose up --build

5. Add to Cursor (or any MCP client):

For direct local use (without Docker):

{
  "mcpServers": {
    "diagram-bridge-mcp": {
      "command": "node",
      "args": ["/path/to/diagram-bridge-mcp/dist/index.js"],
      "enabled": true
    }
  }
}

For Docker-based setup (recommended):

{
  "mcpServers": {
    "diagram-bridge-mcp": {
      "command": "docker",
      "args": [
        "exec", 
        "-i", 
        "diagram-bridge-mcp", 
        "node", 
        "dist/index.js"
      ],
      "enabled": true
    }
  }
}

Note: The MCP protocol uses STDIO communication. The HTTP endpoints (:3000/health) are only for Docker monitoring, not for MCP client connections.

5. Start using: The server provides three MCP tools ready for use!

💡 Usage Example

Here's a simple prompt to demonstrate the complete workflow:

"Choose the best diagram format for visualizing a current project architecture, then generate the diagram code and render it to an image file. Save the result as 'architecture-diagram'."

This single prompt will:

1. Analyze your request and recommend the optimal format
2. Get specific instructions for creating the diagram in that format
3. Create and render the final diagram to a PNG/SVG file

🎨 Examples Gallery

Want to see what's possible? Check out Examples Gallery

🛠️ Tools Overview

help_choose_diagram

Purpose: Intelligent format selection based on your requirements

• Analyzes your request using AI-powered heuristics
• Provides confidence-scored recommendations
• Works with format constraints when needed
• Generates structured prompts for optimal LLM decision-making

Example: "I need to show database relationships" → Recommends Mermaid ER diagram format with detailed reasoning

get_diagram_instructions

Purpose: Generate format-specific coding instructions

• Creates tailored

... View full README on GitHub