Excalidraw

You can run the Excalidraw diagram MCP server locally to programmatically create, connect, and manage diagram elements through a lightweight command protocol. This server lets you add shapes, draw connections, and fetch a full diagram state via simple tool calls, enabling seamless integration with your workflow and editor tooling.

How to use

To use the Excalidraw MCP server, connect with an MCP client configured to talk to a local stdio MCP endpoint. You will issue tool calls to create nodes and edges, delete elements, and retrieve the full diagram state as a markdown representation. Use a client that supports the MCP protocol and point it to the stdio server configuration shown in the installation steps.

How to install

Prerequisites: ensure Node.js is installed and is version 18.0.0 or newer.

// Node.js is already installed on your system. Verify the version:
node -v

Install or prepare the MCP client integration by using the following MCP configuration snippet in your environment. This registers the excalidraw MCP server and points to your diagram file.

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["-y", "@cmd8/excalidraw-mcp", "--diagram", "/path/to/diagram.excalidraw"]
    }
  }
}

If you are using different MCP clients, configure them similarly to point to the same diagram file using the same command and arguments shown above.

Additional sections

Configuration notes: The MCP server is invoked via a local runtime using the npx command to load the Excalidraw MCP package and the --diagram flag to specify your diagram file path. The standard invocation format is ready to be copied into your MCP client configuration. No additional server endpoints are required for local usage.

Security: This setup runs locally and does not expose an external network endpoint by default. If you plan to expose the MCP endpoint over the network, apply appropriate authentication and access controls at the client or environment level.

Troubleshooting tips: If the server does not start, verify that Node.js 18+ is installed, that the diagram path exists and is accessible, and that your MCP client is configured with the exact command and arguments shown. Check your environment for any restrictions on executing npx or disk permissions for the diagram file.

Tools and capabilities

The server provides these core tools for diagram composition and inspection:

• Create a new node
• Create an edge between two nodes (by ID or label)
• Delete an element by ID or label
• Get a full markdown representation of the diagram state (nodes, edges, labels, frames, colors)

Available tools

createNode

Create a new node (shape with label) in the diagram. Returns the created node ID.

createEdge

Create an arrow connecting two nodes. Nodes can be referenced by ID or by label text.

deleteElement

Delete a node or edge from the diagram by ID or label.

getFullDiagramState

Return a markdown representation of the complete diagram, including nodes, relationships, labels, frames, and colors.