# excalidash-mcp

MCP server that lets Claude (and other MCP clients) create, list, read, update,
and delete drawings in [ExcaliDash](https://github.com/ZimengXiong/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`](https://github.com/ZimengXiong/ExcaliDash/blob/main/backend/src/server/csrf.ts)
→ `isNonBrowserApiKeyBearerRequest`).

## Claude Desktop / Claude Code config

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

For Claude Code, the equivalent CLI:

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

## Local development

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

Smoke-test the MCP surface:

```bash
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