@modudraft/mcp

Model Context Protocol (MCP) server for Modudraft — the system-design diagramming tool.

Connect your AI assistant (Claude, Cursor, Copilot, etc.) to your Modudraft diagrams and let it build and edit architecture, sequence, DB schema, API, cloud, network, and data-flow diagrams for you.

Requirements

• Modudraft Pro account — API access is a Pro feature
• Node.js 18+
• An API key from your Modudraft dashboard

Setup

1. Create an API key

Go to your Modudraft dashboard → Settings → API Keys → Create new key.

Copy the key — you'll only see it once.

2. Add to your MCP config

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "modudraft": {
      "command": "npx",
      "args": ["-y", "@modudraft/mcp"],
      "env": {
        "MODUDRAFT_API_KEY": "mdft_your_key_here"
      }
    }
  }
}

Cursor (.cursor/mcp.json in your project or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "modudraft": {
      "command": "npx",
      "args": ["-y", "@modudraft/mcp"],
      "env": {
        "MODUDRAFT_API_KEY": "mdft_your_key_here"
      }
    }
  }
}

Environment variables

| Variable | Required | Description | |---|---|---| | MODUDRAFT_API_KEY | Yes | Your mdft_… API key | | MODUDRAFT_API_URL | No | Override API base URL (default: https://api.modudraft.com) |

Tools

Diagram management

| Tool | Description | |---|---| | list_diagrams | List all your diagrams | | create_diagram | Create a new diagram | | get_diagram | Get full diagram state + missing-metadata hints | | delete_diagram | Move diagram to Bin | | clear_diagram | Remove all content from a diagram | | layout_diagram | Auto-arrange nodes (dagre, supports LR/TB/RL/BT) | | get_share_link | Get or create a share link |

Architecture nodes & edges

| Tool | Description | |---|---| | add_node | Add a component (compute, database, queue, gateway, etc.) | | update_node | Update label, tool, or archetype | | delete_node | Remove a node and its connections | | add_edge | Connect two nodes with optional label and protocol | | update_edge | Update edge label or protocol | | delete_edge | Remove a connection | | add_boundary | Add a grouping boundary box | | add_note | Add a sticky note annotation |

Node metadata

| Tool | Description | |---|---| | set_node_metadata | Set a configuration property on a node (host, port, framework, region, etc.) | | suggest_metadata | Find nodes with missing configuration and suggest what to fill in | | get_node_schema | Get expected metadata fields for an archetype |

Sequence diagram

| Tool | Description | |---|---| | add_sequence_message | Add a message between participants | | add_sequence_participant | Register a named participant | | clear_sequence | Remove all sequence messages | | auto_sequence | Derive sequence messages from the architecture edges | | add_sequence_fragment | Wrap messages in a loop / alt / opt / par fragment | | update_sequence_fragment | Change a fragment's kind, condition, or message list | | delete_sequence_fragment | Remove a fragment |

DB schema (ER diagram)

| Tool | Description | |---|---| | add_db_table | Add a database table with columns | | update_db_table | Replace a table's columns | | delete_db_table | Remove a table | | export_er_diagram | Export schema as SQL DDL |

API schema (OpenAPI)

| Tool | Description | |---|---| | add_api_endpoint | Add a REST/GraphQL/gRPC endpoint | | update_api_endpoint | Update endpoint details | | delete_api_endpoint | Remove an endpoint | | export_openapi | Export schema as OpenAPI 3.0 JSON |

Cloud diagram

| Tool | Description | |---|---| | add_cloud_resource | Add a cloud resource (cluster, VPC, service, database, queue, etc.) | | update_cloud_resource | Rename or change the type of a cloud resource | | delete_cloud_resource | Remove a cloud resource |

Network diagram

| Tool | Description | |---|---| | add_network_device | Add a network device (router, switch, firewall, etc.) | | update_network_device | Rename or change the type of a network device | | delete_network_device | Remove a network device |

Data flow diagram

| Tool | Description | |---|---| | add_data_flow_stage | Add a pipeline stage (source, transform, sink, etc.) | | update_data_flow_stage | Rename or change the type of a data flow stage | | delete_data_flow_stage | Remove a data flow stage | | reorder_data_flow_stages | Set the order of all stages in a data flow diagram |

File import

| Tool | Description | |---|---| | scan_project | Scan a directory and list all importable files (docker-compose, K8s, Terraform, SQL, Prisma, OpenAPI, etc.) | | read_file | Read any file from the filesystem | | import_file | Import a file into a diagram — auto-detects format |

Supported import formats:

• Architecture: docker-compose.yml → nodes + edges
• Cloud: Kubernetes YAML, Terraform .tf, AWS CloudFormation YAML/JSON
• DB schema: SQL DDL, schema.prisma, DBML, schema.rb (Rails), TypeORM entities, SQLAlchemy models, dbt schema.yml
• API: OpenAPI 2.x/3.x, GraphQL SDL, Protocol Buffers .proto, Postman collection, Insomnia export v4, AsyncAPI
• Context (no diagram change): .env files (sensitive values always redacted), package.json, go.mod, requirements.txt, Gemfile, pom.xml, Cargo.toml

Export

| Tool | Description | |---|---| | export_mermaid | Export as Mermaid flowchart or ER diagram (paste into GitHub Markdown) | | export_plantuml | Export as PlantUML component diagram | | export_drawio | Export as draw.io / diagrams.net XML | | export_terraform | Generate Terraform resource stubs from the cloud tab | | export_k8s_yaml | Generate Kubernetes YAML manifests from the cloud tab | | export_to_file | Write any export format directly to a local file |

Validation & diff

| Tool | Description | |---|---| | validate_diagram | Check a diagram for issues: dangling edges, orphaned nodes, FK integrity, missing PKs, duplicate routes, etc. | | diff_diagram | Compare two diagrams and return a structured list of what changed (added/removed/modified) |

Cross-diagram intelligence

| Tool | Description | |---|---| | find_shared_services | Find nodes that appear in multiple diagrams — useful for shared infrastructure audits | | suggest_connections | Detect likely missing edges based on archetype pairs | | suggest_architecture | Generate a suggested node/edge structure from a text description | | clone_diagram | Deep-copy a diagram as a starting template |

Discovery (static, no API call)

| Tool | Description | |---|---| | list_archetypes | All component archetypes with metadata field schemas | | list_tools | Available tech tools per archetype (postgresql, redis, kafka, etc.) | | list_protocols | Valid edge protocol values |

Org context

| Tool | Description | |---|---| | get_org_context | Get cached org context — existing tools, protocols, naming patterns | | refresh_org_context | Force a refresh of the org context cache |

Example prompts

"Scan my project at ~/code/myapp and import everything you find into diagram X."

"Import our docker-compose.yml and create an architecture diagram."

"Import schema.prisma and generate the DB schema tab."

"Export the architecture as a Mermaid diagram and save it to ./docs/architecture.md."

"Generate Terraform stubs for everything in the cloud tab and save to ./infra/main.tf."

"Validate diagram X — are there any issues with the schema or missing connections?"

"Compare diagram A and diagram B — what changed between the two designs?"

"What services appear in more than one of our diagrams?"

"Suggest an architecture for a checkout service with Stripe, Postgres, Redis, and an event queue."

"Create a diagram of a typical e-commerce backend with a React frontend, API gateway, user service, product service, order service, PostgreSQL databases, Redis cache, and Kafka queue. Connect them and layout the diagram."

"Add the DB schema for the order service — orders, order_items, and payments tables."

"Auto-generate a sequence diagram from the architecture."

"What metadata is missing from the diagram nodes? Fill in the hosts and ports based on our .env file."

How it works

Each tool call requires a diagram_id. The server reads the current diagram from the Modudraft API, applies the change in memory, and writes it back — with a 150ms debounce batch so rapid sequential edits (add 10 nodes, add edges) result in a single API round trip. Changes appear instantly in the Modudraft web app.

The get_diagram response includes a hints array listing nodes with empty metadata fields so your AI assistant knows what context to ask you for.

Security

• API keys are hashed (SHA-256) server-side and never stored in plain text
• Keys can be revoked at any time from the dashboard
• All requests use HTTPS
• .env file imports redact all secrets — only topology metadata (host, port, database name, region) is ever extracted; passwords, tokens, and API keys are always replaced with [REDACTED]

License

MIT © Modudraft