excalidash-mcp

MCP server that lets Claude (and other MCP clients) create, list, read, update, and delete drawings in ExcaliDash via its REST API.

End state: add one URL to your Claude config and say "畫個 XX 流程圖" — the drawing appears in your ExcaliDash dashboard.

Tools

• create_drawing(name, elements?, appState?) → { id, url, name }
• update_drawing(id, elements, appState?)
• list_drawings() → Array<{ id, name, updatedAt, url }>
• get_drawing(id) → { id, name, elements, appState, url }
• delete_drawing(id)

Element JSON is passed straight through to ExcaliDash — use the standard Excalidraw element format (type, x, y, width, height, etc.).

Endpoints

• POST /mcp — Streamable HTTP MCP endpoint (stateless mode)
• GET /health — JSON health check (also reports current authMode)

Environment

Var	Required	Default	Notes
EXCALIDASH_URL	yes	https://excalidash.bamolab.org	Base URL of the ExcaliDash backend (the same host that serves the frontend — the /api/... prefix is added automatically)
EXCALIDASH_API_KEY	one of two	–	An exd_... API key — generate in ExcaliDash → account → API keys. Must have drawings:read + drawings:write scopes
EXCALIDASH_EMAIL + EXCALIDASH_PASSWORD	one of two	–	Fallback email+password login (uses cookie session + CSRF)
PORT	no	8080	HTTP listen port

The server fail-fasts on startup if no credentials are configured.

Prefer the API key path — it skips ExcaliDash's CSRF/cookie dance entirely because the backend treats Bearer requests without an Origin/Referer header as non-browser API requests (see backend/src/server/csrf.ts → isNonBrowserApiKeyBearerRequest).

Claude Desktop / Claude Code config

{
  "mcpServers": {
    "excalidash": {
      "type": "http",
      "url": "https://excalidash-mcp.bamolab.org/mcp"
    }
  }
}

For Claude Code, the equivalent CLI:

claude mcp add --transport http excalidash https://excalidash-mcp.bamolab.org/mcp

Local development

npm install
npm run build
EXCALIDASH_API_KEY=exd_... npm start

Smoke-test the MCP surface:

curl -s -X POST http://localhost:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

License

MIT