excalidraw

This MCP server integrates Excalidraw diagrams into your Model Context Protocol ecosystem. By running the MCP server with the provided diagram path, you expose a set of diagram manipulation tools that can be invoked via MCP-compatible clients. The server supports creating nodes and edges, deleting elements, and retrieving a full markdown representation of the diagram for easy rendering or documentation. Available tools include: createNode to add a new labeled shape, createEdge to connect two nodes by ID or label, deleteElement to remove a node or edge, and getFullDiagramState to fetch a complete, markdown-formatted view of the diagram with its structure, relationships, and styling. To use these tools, point your MCP-enabled client at the excalidraw server name in your MCP configuration and call the corresponding tool via your client’s MCP interface, supplying any required parameters (e.g., node labels, element IDs, or a diagram file path).

Prerequisites:

• Node.js >= 18.0.0
• Access to run npm/npx commands

Installation steps (examples shown using the MCP integration methods in the README):

1. Install Node.js (if not already installed)

• Visit https://nodejs.org/ and install the latest LTS version compatible with Node.js >= 18.

2. Install and run via npx (Minted MCP approach shown in the README)

• The server is intended to be executed through npx with the package @cmd8/excalidraw-mcp. Use the example configuration provided in the README to add the MCP to your environment.

3. Add the MCP to Cursor (example JSON snippet)

• Ensure your Cursor MCP config includes:

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

4. Alternative installation methods (per tool integration shown in the README):

• Claude Code:

claude mcp add excalidraw -- npx -y @cmd8/excalidraw-mcp --diagram /path/to/diagram.excalidraw

• Amp:

amp mcp add excalidraw -- npx -y @cmd8/excalidraw-mcp --diagram /path/to/diagram.excalidraw

• VS Code:

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

• Windsurf:

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

• Claude Desktop:

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

• OpenAI Codex:

[mcp_servers.excalidraw]
command = "npx"
args = ["-y", "@cmd8/excalidraw-mcp", "--diagram", "/path/to/diagram.excalidraw"]

5. Verify the server is running by invoking a tool (e.g., getFullDiagramState) through your MCP client and ensure you receive a markdown diagram representation or IDs for nodes/edges.

Notes and tips:

• The diagram path is required for the --diagram flag; ensure the file exists and is accessible to the runtime.
• If you encounter permission or network issues with npx, run npm install -g npm and update npm, or run via a local installation of the package if preferred.
• The available tools are createNode, createEdge, deleteElement, and getFullDiagramState. You can reference nodes by ID or by label text when creating edges or deleting elements.
• The server returns a markdown representation of the full diagram through getFullDiagramState, which is useful for documentation or rendering in compatible clients.
• Ensure your MCP client is configured to handle the markdown output from getFullDiagramState or to process IDs for node/edge operations.