Draw.io MCP server
Let's do some Vibe Diagramming with the most wide-spread diagramming tool called Draw.io (Diagrams.net).
Introduction
The Draw.io MCP server is a Model Context Protocol (MCP) implementation that brings powerful diagramming capabilities to AI agentic systems. This integration enables:
- Seamless Draw.io Integration: Connect your MCP-powered applications with Draw.io's rich diagramming functionality
- Programmatic Diagram Control: Create, modify, and manage diagram content through MCP commands
- Intelligent Diagram Analysis: Retrieve detailed information about diagrams and their components for processing by AI agents
- Agentic System Development: Build sophisticated AI workflows that incorporate visual modeling and diagram automation
As an MCP-compliant tool, it follows the standard protocol for tool integration, making it compatible with any MCP client. This implementation is particularly valuable for creating AI systems that need to:
- Generate architectural diagrams
- Visualize complex relationships
- Annotate technical documentation
- Create flowcharts and process maps programmatically
The tool supports bidirectional communication, allowing both control of Draw.io instances and extraction of diagram information for further processing by AI agents in your MCP ecosystem.
Requirements
To use the Draw.io MCP server, you'll need:
Core Components
- Node.js (v20 or higher) - Runtime environment for the MCP server
- Draw.io MCP Browser Extension - Enables communication between Draw.io and the MCP server
MCP Ecosystem
- MCP Client (e.g., MCP Inspector) - For testing and debugging the integration
- LLM with Tools Support - Any language model capable of handling MCP tool calls (e.g., GPT-4, Claude 3, etc.)
Optional for Development
- pnpm - Preferred package manager
- Chrome DevTools - For debugging when using
--inspectflag
Note: The Draw.io desktop app or web version must be accessible to the system where the MCP server runs.
Configuration
WebSocket Port
The server listens on port 3333 by default for WebSocket connections from the browser extension. You can customize this port using the --extension-port or -p flag.
Default behavior (port 3333):
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server"]
}
}
}
Custom port (e.g., port 8080):
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
}
}
}
Note: When using a custom port, ensure the browser extension is configured to connect to the same port.
HTTP Transport Port
The server can expose a streamable HTTP MCP transport on port 3000. Change this using the --http-port flag:
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server", "--transport", "http", "--http-port", "4000"]
}
}
}
Transport Selection
By default only the stdio transport starts. Limit or combine transports with the --transport flag:
--transport stdio– start only stdio (CLI-friendly)--transport http– start only the HTTP transport (for remote clients)--transport stdio,http– start both transports
Running the streamable HTTP transport
Use the streamable HTTP transport when you need to reach the MCP server over the network (for example from a remote agent runtime). The Draw.io browser extension is still required, and you must opt in to the HTTP transport.
- Start the server with HTTP enabled (optionally alongside stdio):
npx -y drawio-mcp-server --transport http --http-port 3000
# or both: npx -y drawio-mcp-server --transport stdio,http --http-port 4000
- Verify the health endpoint:
curl http://localhost:3000/health
# { "status": "ok" }
- Point your MCP client to the
/mcpendpoint (http://localhost:3000/mcpby default). CORS is enabled for all origins so you can call it from a browser-based client as well.
Installation
Connecting with Claude Desktop
-
Install Claude Desktop
-
Open or create the configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
Update it to include this server:
Using npm
{
"mcpServers":{
"drawio":{
"command":"npx",
"args":[
"-y",
"drawio-mcp-server"
]
}
}
}
Using pnpm
{
"mcpServers":{
"drawio":{
"command":"pnpm",
"args":[
"dlx",
"drawio-mcp-server"
]
}
}
}
To use a custom extension port (e.g., 8080), add "--extension-port", "8080" to the args array:
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
}
}
}
- Restart Claude Desktop
Connecting with oterm
This is an alternative MCP client in case you like terminal and you plan to connect to your own Ollama instance.
The configuration is usually in: ~/.local/share/oterm/config.json
Using npm
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": [
"-y",
"drawio-mcp-server"
]
}
}
}
Using pnpm
{
"mcpServers": {
"drawio": {
"command": "pnpm",
"args": [
"dlx",
"drawio-mcp-server"
]
}
}
}
To use a custom extension port (e.g., 8080), add "--extension-port", "8080" to the args array:
{
"mcpServers": {
"drawio": {
"command": "npx",
"args": ["-y", "drawio-mcp-server", "--extension-port", "8080"]
}
}
}
Connect with Zed
- Open the Zed Preview application.
- Click the Assistant (✨) icon in the bottom right corner.
- Click Settings in the top right panel of the Assistant.
- In the Context Servers section, click + Add Context Server.
- Configure with the following:
Using npm
{
/// The name of your MCP server
"drawio": {
/// The path to the executable
"command": "npx",
/// The arguments to pass to the executable
"args": [
"-y",
"drawio-mcp-server"
],
/// The environment variables to set for the executable
"env": {}
}
}
Using pnpm
{
/// The name of your MCP server
"drawio": {
/// The path to the executable
"command": "pnpm",
/// The arguments to pass to the executable
"args": [
"dlx",
"drawio-mcp-server"
],
/// The environment variables to set for the executable
"env": {}
}
}
To use a custom extension port (e.g., 8080), add "--extension-port", "8080" to the args array:
{
"drawio": {
"command": "npx",
"args": [
"-y",
"drawio-mcp-server",
"--extension-port",
"8080"
],
"env": {}
}
}
Connecting with Codex
Edit the configuration usually located in: ~/.codex/config.toml
Using npm
[mcp_servers.drawio]
command = "npx"
args = [
"-y",
"drawio-mcp-server"
]
Using pnpm
[mcp_servers.drawio]
command = "pnpm"
args = [
"dlx",
"drawio-mcp-server"
]
To use a custom extension port (e.g., 8080), add "--extension-port", "8080" to the args array:
Using npm
[mcp_servers.drawio]
command = "npx"
args = [
"-y",
"drawio-mcp-server",
"--extension-port",
"8080"
]
To connect to a locally running MCP with Streamable HTTP transport:
[mcp_servers.drawio]
url = "http://localhost:3000/mcp"
Browser Extension Setup
In order to control the Draw.io diagram, you need to install dedicated Browser Extension.
- Open Draw.io in your browser
- Install the Draw.io MCP Browser Extension from a web store or use other means
Important: If you configured the MCP server to use a custom port (not 3333), you must configure the browser extension to use the same port. See the extension documentation for port configuration instructions.
Sponsoring
If you enjoy the project or find it useful, consider supporting its continued development.
lightning invoice:
lnbc1p5f8wvnpp5kk0qt60waplesw3sjxu7tcqwmdp6ysq570dc4ln52krd3u5nzq6sdp82pshjgr5dusyymrfde4jq4mpd3kx2apq24ek2uscqzpuxqr8pqsp5gvr72xcs883qt4hea6v3u7803stcwfnk5c9w0ykqr9a40qqwnpys9qxpqysgqfzlhm0cz5vqy7wqt7rwpmkacukrk59k89ltd5n642wzru2jn88tyd78gr4y3j6u64k2u4sd4qgavlsnccl986velrg3x0pe95sx7p4sqtatttp
lightning address:
ladislav@blink.sv
Features
The Draw.io MCP server provides the following tools for programmatic diagram interaction:
Diagram Inspection Tools
-
get-selected-cellRetrieves the currently selected cell in Draw.io with all its attributes Returns: JSON object containing cell properties (ID, geometry, style, value, etc.) -
get-shape-categoriesRetrieves available shape categories from the diagram's library Returns: Array of category objects with their IDs and names -
get-shapes-in-categoryRetrieves all shapes in a specified category from the diagram's library Parameters:category_id: Identifier of the category to retrieve shapes from Returns: Array of shape objects with their properties and styles
-
get-shape-by-nameRetrieves a specific shape by its name from all available shapes Parameters:shape_name: Name of the shape to retrieve Returns: Shape object including its category and style information
-
list-paged-modelRetrieves a paginated view of all cells (vertices and edges) in the current Draw.io diagram. This tool provides access to the complete model data with essential fields only, sanitized to remove circular dependencies and excessive data. It allows to filter based on multiple criteria and attribute boolean logic. Useful for programmatic inspection of diagram structure without overwhelming response sizes.
Diagram Modification Tools
-
add-rectangleCreates a new rectangle shape on the active Draw.io page with customizable properties:- Position (
x,ycoordinates) - Dimensions (
width,height) - Text content
- Visual style (fill color, stroke, etc. using Draw.io style syntax)
- Position (
-
add-edgeCreates a connection between two cells (vertexes) Parameters:source_id: ID of the source celltarget_id: ID of the target celltext: Optional text label for the edgestyle: Optional style properties for the edge
-
delete-cell-by-idRemoves a specified cell from the diagram Parameters:cell_id: ID of the cell to delete
-
add-cell-of-shapeAdds a new cell of a specific shape type from the diagram's library Parameters:shape_name: Name of the shape to createx,y: Position coordinates (optional)width,height: Dimensions (optional)text: Optional text contentstyle: Optional additional style properties
-
set-cell-shapeApplies a library shape's style to an existing cell Parameters:cell_id: ID of the cell whose appearance should changeshape_name: Name of the library shape whose style should be applied
-
set-cell-dataStores or updates a custom attribute on a cell Parameters:cell_id: ID of the cell to updatekey: Attribute name to setvalue: Attribute value (stored as a string internally)
-
edit-cellUpdates an existing vertex/shape cell in place by ID Parameters:cell_id: ID of the cell whose properties should change (required)text,x,y,width,height,style: Optional fields to update on the cell; omitted properties stay as-is
-
edit-edgeUpdates an existing edge connection between cells by ID Parameters:cell_id: ID of the edge cell to update (required)text: Optional edge label textsource_id,target_id: Optional IDs of new source/target cellsstyle: Optional replacement style string
Related Resources
Star History
Assessments
