@excaliwow/mcp

The Excaliwow Model Context Protocol server — lets an AI agent create, read, render, manage, and edit diagrams in your Excaliwow account through the same public REST API (/api/v1) the CLI uses. It runs over stdio, so any MCP client (Claude Desktop, Claude Code, etc.) can launch it with npx.

The public excaliwow/mcp repository contains distribution metadata and documentation for this package; the hosted application source is not published there.

Install

First mint a Personal Access Token at https://excaliwow.com/app/settings (Settings → Developer / API tokens) with read + write capabilities — enough for sixteen of the eighteen tools. Add delete only if you want the agent to trash and restore diagrams (see Security notes). Pass it as EXCALIWOW_TOKEN.

Claude Code (CLI)

One command. --scope local stores the server in your own settings, so the token never lands in a file you might commit. Export the token first so the literal PAT never lands in your shell history — --env NAME="$NAME" passes the value through without typing it a second time on the command line:

export EXCALIWOW_TOKEN=excw_pat_…
claude mcp add excaliwow --scope local \
  --env EXCALIWOW_TOKEN="$EXCALIWOW_TOKEN" \
  -- npx -y @excaliwow/mcp

Claude Desktop (and other JSON-config clients)

Add it to your client’s config file (e.g. Claude Desktop’s claude_desktop_config.json, or your client’s MCP settings — see your client’s MCP setup docs). The spec is unversioned, so npx -y always launches the latest release — you pick up new tools and fixes automatically, with nothing to bump:

{
  "mcpServers": {
    "excaliwow": {
      "command": "npx",
      "args": ["-y", "@excaliwow/mcp"],
      "env": {
        "EXCALIWOW_TOKEN": "excw_pat_…"
      }
    }
  }
}

The server reads EXCALIWOW_TOKEN per call from the environment (or, if you also use @excaliwow/cli and have run excaliwow auth login, that stored login) and never writes the token to disk itself.

Troubleshooting

“Not authenticated” / 401 / the agent’s tool calls fail. The server starts even without a token (so it can list its tools), so a missing or invalid EXCALIWOW_TOKEN only surfaces when the agent first calls a tool. Starting with no token prints a one-line EXCALIWOW_TOKEN is not set warning to stderr. To check a token directly, run the health probe — it makes one authenticated read and prints a clear verdict (ok, 401 — token is invalid or expired, or could not reach when the API itself is unreachable) and exits with a matching code (0 ok, 1 missing/invalid token, 2 unreachable):

npx -y @excaliwow/mcp --health

CLI flags

| Flag | Effect |