Encima Board MCP Server

A Model Context Protocol server that lets AI clients (Claude Desktop, Claude Code, Cursor, ChatGPT Developer Mode) read and edit Encima Board whiteboards via the backend REST API.

v1 scope: stdio transport only. Remote Streamable HTTP + Keycloak OAuth is on the v2 roadmap.

Tools

| Tool | What it does | |---|---| | list_drawings | Paginated list (id, name, version, collectionId, timestamps). | | get_drawing | Full drawing (elements, appState, files, version). | | create_drawing | Create a blank drawing. | | rename_drawing | Change name only. | | list_collections | List user's collections. | | update_scene | Bulk per-element patches by id (move, recolor, resize, rename). | | add_section | Append a section (fork-specific rectangle + label). | | add_sticky_note | Append a sticky note (yellow / pink / green / blue). | | add_rectangle | Append a plain rectangle with optional text. | | connect_with_arrow | Append an arrow binding two existing elements by id. |

Install

You need Node.js 20+ and a Personal Access Token (see Get a PAT below). Then add one entry to your MCP client config — that is it, no clone, no build, no .bat. npx fetches and runs the latest published version on first use.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "encima-board": {
      "command": "npx",
      "args": ["-y", "@encimabv/board-mcp"],
      "env": {
        "ENCIMA_BOARD_API_URL": "https://board.encima.be/api",
        "ENCIMA_BOARD_PAT": "excalidash_pat_..."
      }
    }
  }
}

Restart Claude Desktop. The Encima Board tools appear in the tools picker.

Cursor

Settings → MCP → add server, paste the same JSON block.

Claude Code

claude mcp add encima-board npx -y @encimabv/board-mcp \
  --env ENCIMA_BOARD_API_URL=https://board.encima.be/api \
  --env ENCIMA_BOARD_PAT=excalidash_pat_...

ChatGPT Developer Mode / generic stdio MCP

Point any stdio-speaking MCP client at npx -y @encimabv/board-mcp with the same two env vars.

Self-hosted backend (local dev)

Override ENCIMA_BOARD_API_URL to your own backend URL, e.g. http://localhost:8001 when running make dev-auth in this repo. Mint the PAT against that backend.

One-click for Claude Desktop (optional)

If you would rather drag-and-drop a bundle than edit JSON, grab the .mcpb from the releases page and double-click. Claude Desktop prompts for the API URL and PAT and stores them in your OS keychain.

Get a PAT

PATs are long-lived Bearer credentials prefixed with excalidash_pat_. Two ways to mint one.

From the web app (preferred once shipped): Settings → Personal Access Tokens → New.

Via curl, from a logged-in browser session against any backend (replace the host as needed):

# 1. Log into the app in your browser. Open DevTools → Application → Cookies.
#    Save the cookies to a file (Copy as cURL is the easiest path).
# 2. Fetch a CSRF token:
CSRF=$(curl -s -b cookies.txt https://board.encima.be/api/csrf-token | jq -r .token)
# 3. Create the PAT:
curl -X POST https://board.encima.be/api/auth/pat \
     -H "Content-Type: application/json" \
     -H "x-csrf-token: $CSRF" \
     -b cookies.txt \
     -d '{"name":"claude-desktop"}'
# → returns { token: "excalidash_pat_...", pat: {...} }
# The token is shown only once. Copy it now.

Example prompts

• "List my drawings."
• "In drawing <id>, add a yellow sticky note at (300, 400) that says 'TODO'."
• "Add a section called 'Backend' at (100, 100), then add a sticky note inside it saying 'auth middleware'."
• "Rename drawing <id> to 'Q2 planning'."
• "Move the element with id <...> to x=500."

Troubleshooting

• 401 Unauthorized — PAT missing, malformed, revoked, or expired. Mint a new one.
• 403 CSRF — your client is not sending Authorization: Bearer excalidash_pat_.... PATs intentionally bypass CSRF; if you see this, the header is being dropped or the cookie auth path was hit instead.
• Tools missing in the picker — restart Claude Desktop after editing the config. Logs at ~/Library/Logs/Claude/ (macOS) or %APPDATA%\Claude\logs\ (Windows).
• 409 version conflict after a retry — the drawing was edited between reads. Ask the AI to re-read and try again.
• Missing ENCIMA_BOARD_API_URL — the env block in the MCP config was not picked up. Fully quit the host app and reopen; some clients only read env on cold start.

Development

Only needed if you want to hack on the server itself or run it directly from the repo.

git clone https://gitlab.encima.be/customers/encima-draw.git
cd encima-draw/mcp
npm install
npm run build           # tsc → dist/
npm run dev             # tsx on src/, hot during edits
npm test

Point your MCP client at the local build with "command": "node", "args": ["/abs/path/to/mcp/dist/index.js"] instead of npx.

To publish a new version:

cd mcp
npm version patch       # or minor/major
npm publish             # runs prepublishOnly → tsc, then publishes

To produce the .mcpb (drag-and-drop installer):

make mcp-pack           # at repo root

Limitations (v1)

• No socket broadcast on AI writes. Collaborators with the drawing open see AI edits only after refresh or reconnect.
• No remote / hosted MCP. mcp.board.encima.be with Keycloak OAuth 2.1 is the v2 plan.
• No rate limiting on PAT writes. Do not run unattended AI loops that hammer PUT.
• Full-scene replacement under the hood. Each tool call re-PUTs the whole scene, which is fine at AI rates (one to ten edits per turn).

License

AGPL-3.0, same as the rest of the fork.