{
  "markdown": "# diagrams-mcp-server\n\n[![PyPI](https://img.shields.io/pypi/v/diagrams-mcp-server)](https://pypi.org/project/diagrams-mcp-server/)\n[![CI](https://github.com/ByteOverDev/diagrams-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ByteOverDev/diagrams-mcp/actions/workflows/ci.yml)\n[![Railway](https://img.shields.io/endpoint?url=https://diagrams-mcp-production.up.railway.app/health&logo=railway)](https://diagrams-mcp-production.up.railway.app/health)\n\nMCP server for generating cloud architecture diagrams, flowcharts, sequence diagrams, and more — powered by three rendering engines: [mingrammer/diagrams](https://github.com/mingrammer/diagrams), [Mermaid](https://mermaid.js.org/), and [PlantUML](https://plantuml.com/).\n\n![Example diagram](https://raw.githubusercontent.com/ByteOverDev/diagrams-mcp/main/assets/hero-diagram.png)\n\n## Getting Started\n\n### Hosted (Recommended)\n\nConnect to the public hosted server — no installation required. All rendering engines and dependencies are pre-installed.\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to your `claude_desktop_config.json` (`Settings` → `Developer` → `Edit Config`):\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"url\": \"https://diagrams-mcp-production.up.railway.app/mcp\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code (CLI)</strong></summary>\n\nRun:\n\n```bash\nclaude mcp add diagrams-mcp https://diagrams-mcp-production.up.railway.app/mcp\n```\n\nOr add to your `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"url\": \"https://diagrams-mcp-production.up.railway.app/mcp\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to your `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"url\": \"https://diagrams-mcp-production.up.railway.app/mcp\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Windsurf</strong></summary>\n\nAdd to your `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"serverUrl\": \"https://diagrams-mcp-production.up.railway.app/mcp\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\nAdd to your `.vscode/mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"diagrams-mcp\": {\n      \"type\": \"http\",\n      \"url\": \"https://diagrams-mcp-production.up.railway.app/mcp\"\n    }\n  }\n}\n```\n\n</details>\n\n### Local Installation\n\n#### Prerequisites\n\nGraphviz is required for the default local/in-process rendering mode. Mermaid CLI and PlantUML are optional — install them only if you need those specific rendering engines locally.\n\n| Dependency | Required for | Install |\n|---|---|---|\n| [Graphviz](https://graphviz.org/) | `render_diagram` (cloud architecture) | `brew install graphviz` |\n| [Mermaid CLI](https://github.com/mermaid-js/mermaid-cli) | `render_mermaid` (flowcharts, sequence, etc.) | `npm install -g @mermaid-js/mermaid-cli` |\n| [Java](https://openjdk.org/) + [PlantUML](https://plantuml.com/) | `render_plantuml` (UML diagrams) | `brew install openjdk` + download [plantuml.jar](https://github.com/plantuml/plantuml/releases) |\n\n> **Note**: The hosted server runs as a slim MCP facade plus a separate renderer service, and has all render dependencies pre-installed in the renderer. Local prerequisites only apply if you're running in-process rendering yourself.\n\n#### Install the server\n\n**Via uvx** (recommended):\n\n```bash\nuvx diagrams-mcp-server\n```\n\n**Via pip:**\n\n```bash\npip install diagrams-mcp-server\n```\n\n**From source:**\n\n```bash\npip install git+https://github.com/ByteOverDev/diagrams-mcp.git\n```\n\n#### Configure your MCP client\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to your `claude_desktop_config.json` (`Settings` → `Developer` → `Edit Config`):\n\n**uvx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"diagrams-mcp-server\"]\n    }\n  }\n}\n```\n\n**pip:**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"diagrams-mcp-server\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code (CLI)</strong></summary>\n\nRun:\n\n```bash\nclaude mcp add diagrams-mcp -- uvx diagrams-mcp-server\n```\n\nOr add to your `.mcp.json`:\n\n**uvx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"diagrams-mcp-server\"]\n    }\n  }\n}\n```\n\n**pip:**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"diagrams-mcp-server\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to your `.cursor/mcp.json`:\n\n**uvx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"diagrams-mcp-server\"]\n    }\n  }\n}\n```\n\n**pip:**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"diagrams-mcp-server\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Windsurf</strong></summary>\n\nAdd to your `~/.codeium/windsurf/mcp_config.json`:\n\n**uvx (recommended):**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\"diagrams-mcp-server\"]\n    }\n  }\n}\n```\n\n**pip:**\n\n```json\n{\n  \"mcpServers\": {\n    \"diagrams-mcp\": {\n      \"command\": \"diagrams-mcp-server\"\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\nAdd to your `.vscode/mcp.json`:\n\n**uvx (recommended):**\n\n```json\n{\n  \"servers\": {\n    \"diagrams-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"diagrams-mcp-server\"]\n    }\n  }\n}\n```\n\n**pip:**\n\n```json\n{\n  \"servers\": {\n    \"diagrams-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"diagrams-mcp-server\"\n    }\n  }\n}\n```\n\n</details>\n\n## Available Tools\n\n### Discovery\n\n- `list_providers()` → `list[str]` — List all diagram providers (`aws`, `gcp`, `k8s`, `azure`, `onprem`, etc.)\n- `list_services(provider)` → `list[str]` — List service categories within a provider (e.g. `aws` → `compute`, `database`, `network`)\n- `list_nodes(provider, service)` → `list[dict]` — List node classes for a provider.service pair with import paths\n- `search_nodes(query)` → `list[dict]` — Search for nodes by keyword across all providers (e.g. \"postgres\", \"lambda\")\n\n### Rendering\n\n- `render_diagram(code)` → `Image` (PNG) — Execute a Python script using [mingrammer/diagrams](https://github.com/mingrammer/diagrams) in a sandboxed subprocess. Returns a rendered cloud architecture diagram.\n- `render_mermaid(definition)` → `Image` (PNG/SVG) — Render a [Mermaid](https://mermaid.js.org/) diagram definition (flowcharts, sequence, class, ER, state, Gantt, and more).\n- `render_plantuml(definition)` → `Image` (PNG) — Render a [PlantUML](https://plantuml.com/) diagram definition (sequence, class, component, activity, state, deployment).\n\n### Cross-Provider Equivalence\n\n- `find_equivalent(node, target_provider?)` → `dict` — Find equivalent services across cloud providers (e.g. `EC2` → `ComputeEngine` on GCP).\n- `list_categories()` → `list[dict]` — List all 30 infrastructure role categories with mapped nodes across providers.\n\n## Resources\n\nThe server provides reference documentation accessible via MCP resource URIs:\n\n| URI | Description |\n|---|---|\n| `diagrams://reference/diagram` | Diagram constructor parameters, defaults, and usage |\n| `diagrams://reference/edge` | Edge operators, labels, styling, and chaining |\n| `diagrams://reference/cluster` | Cluster nesting, styling, and graph attributes |\n| `diagrams://reference/mermaid` | Mermaid syntax examples for 6 diagram types |\n| `diagrams://reference/plantuml` | PlantUML syntax examples for 6 diagram types |\n\n## Examples\n\n### Cloud Architecture (mingrammer/diagrams)\n\n> \"Draw an AWS architecture with an ALB routing to two ECS services, backed by RDS and ElastiCache\"\n\n```python\nfrom diagrams import Diagram, Cluster\nfrom diagrams.aws.network import ALB\nfrom diagrams.aws.compute import ECS\nfrom diagrams.aws.database import RDS, ElastiCache\n\nwith Diagram(\"ECS Service\", direction=\"LR\"):\n    lb = ALB(\"ALB\")\n\n    with Cluster(\"ECS Cluster\"):\n        services = [ECS(\"Web\"), ECS(\"API\")]\n\n    lb >> services\n    services[0] >> ElastiCache(\"Cache\")\n    services[1] >> RDS(\"Database\")\n```\n\n### Flowchart (Mermaid)\n\n> \"Create a flowchart showing a CI/CD pipeline\"\n\n![Mermaid flowchart](https://raw.githubusercontent.com/ByteOverDev/diagrams-mcp/main/assets/mermaid-example.png)\n\n### Sequence Diagram (PlantUML)\n\n> \"Show the authentication flow between a client, API gateway, and auth service\"\n\n![PlantUML sequence diagram](https://raw.githubusercontent.com/ByteOverDev/diagrams-mcp/main/assets/plantuml-example.png)\n\n```plantuml\n@startuml\nClient -> \"API Gateway\": POST /login\n\"API Gateway\" -> \"Auth Service\": Validate credentials\n\"Auth Service\" --> \"API Gateway\": JWT token\n\"API Gateway\" --> Client: 200 OK + token\nClient -> \"API Gateway\": GET /data (Bearer token)\n\"API Gateway\" -> \"Auth Service\": Verify token\n\"Auth Service\" --> \"API Gateway\": Valid\n\"API Gateway\" --> Client: 200 OK + data\n@enduml\n```\n\n## Development\n\n```bash\n# Clone and install\ngit clone https://github.com/ByteOverDev/diagrams-mcp.git\ncd diagrams-mcp\npip install -e \".[dev]\"\n\n# Run tests\npytest\n\n# Lint and format\nruff check .\nruff format .\n\n# Run the MCP server locally (stdio mode)\ndiagrams-mcp-server\n```\n\n### Split Facade/Renderer Mode\n\nFor hosted deployments, the MCP server can run as a lightweight facade that delegates render work to a separate renderer service. This keeps the always-on MCP process small while Graphviz, Chromium, Mermaid CLI, Java, and PlantUML live only in the renderer image.\n\n```bash\n# Terminal 1: renderer service\nRENDERER_HOST=0.0.0.0 RENDERER_PORT=8001 diagrams-renderer-server\n\n# Terminal 2: HTTP MCP facade delegating to the renderer\nFASTMCP_TRANSPORT=http \\\nFASTMCP_HOST=0.0.0.0 \\\nFASTMCP_PORT=8000 \\\nDIAGRAMS_RENDERER_MODE=remote \\\nDIAGRAMS_RENDERER_URL=http://127.0.0.1:8001 \\\ndiagrams-mcp-server\n```\n\nDocker/Railway examples are included:\n\n| File | Purpose |\n|---|---|\n| `Dockerfile.facade` | Slim MCP facade image without renderer-only binaries |\n| `Dockerfile.renderer` | Renderer image with Graphviz, Chromium, Mermaid CLI, Java, and PlantUML |\n| `railway.facade.toml` | Example Railway facade service config |\n| `railway.renderer.toml` | Example Railway renderer service config |\n\nKey environment variables:\n\n| Variable | Purpose |\n|---|---|\n| `DIAGRAMS_RENDERER_MODE=remote` | Makes the facade use the HTTP renderer service |\n| `DIAGRAMS_RENDERER_URL` | Renderer base URL, for example `http://diagrams-renderer.railway.internal:8080` |\n| `DIAGRAMS_IMAGE_STORE_DIR` | Optional file-backed temporary image store directory |\n| `BASE_URL` | Optional public base URL used when returning absolute download links |\n\n## Supported Providers\n\nThe `render_diagram` tool supports all providers from the [mingrammer/diagrams](https://diagrams.mingrammer.com/docs/nodes/aws) library, including:\n\n**AWS**, **GCP**, **Azure**, **Kubernetes**, **On-Premise**, **AlibabaCloud**, **OCI**, **OpenStack**, **DigitalOcean**, **Elastic**, **Outscale**, **Generic**, and **Custom** nodes.\n\nUse `list_providers()` and `search_nodes(query)` to discover available nodes.\n\n## License\n\nMIT\n\n<!-- mcp-name: io.github.mskry/diagrams-mcp-server -->\n",
  "bytes": 11218,
  "sha": "79f856a6a9e907d425b5dcefe6872322cc13e1d9544c0eafba8ffc114d6500b4",
  "repo_slug": "byteoverdev/diagrams-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mskry_diagrams_mcp_server_fa45d4c0/readme"
}