Developer platform

MCP server

Connect an AI agent to your Excaliwow account. The MCP server lets Claude and other clients create, read, render, and edit your diagrams through a small set of tools.

What it is

@excaliwow/mcp is a Model Context Protocol server that runs over stdio. Any MCP client (Claude Desktop, Claude Code, and others) launches it on demand with npx, so there is nothing to install or keep running yourself. The agent works against your hosted account through the same operations the CLI and REST API expose.

Install

Add the server to your MCP client's config file (for Claude Desktop that is claude_desktop_config.json; other clients have their own MCP settings). Set EXCALIWOW_TOKEN to a Personal Access Token you mint at excaliwow.com/app/settings.

claude_desktop_config.json

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

Pinning the version is recommended. Without a pin, npx -y always pulls the newest release into a process that holds a token to your account. Bump the pinned version deliberately, once you have reviewed the release. For more on tokens and scopes, see Authentication.

Tools

The server exposes five tools, scoped to safe agent use.

Tool	Description
`generate_diagram`	Create a diagram from the node/edge DSL. Returns the editor URL.
`read_diagram`	Return a compact summary (title and per-type element counts) plus a rendered PNG.
`list_diagrams`	Page through the diagrams in your account.
`move_diagram`	Move a diagram into a folder, or back to the root.
`edit_diagram`	Additively merge a DSL fragment: add nodes and edges, or update a node's style or label.

Safe by design

read_diagram returns a summary and a rendered PNG, never the raw scene. And making a diagram public is deliberately not an agent tool, so a misled agent cannot expose one. Publish from the dashboard or the CLI instead.

DSL discovery

The agent does not need to read these docs to write diagrams. The grammar and a worked example ride along in the generate_diagram tool description, and the full reference is served as an MCP resource at excaliwow://dsl/reference. You can read the same content in the Diagram DSL reference.

Environment variables

Variable	Type	Description
`EXCALIWOW_TOKEN`*	string	Your Personal Access Token. Required for a standalone install. The server reads it per call from the environment and never writes it to disk.
`EXCALIWOW_API_URL`	string	API origin. Defaults to https://excaliwow.com. Normally leave it unset.

Security notes

Treat the config like a secrets file

Pin the version in your client config rather than floating on the newest release, and review the release notes before bumping.
The token is a credential equal to read-write access to your account. There is no separate per-capability scope, so treat it as full read-write.
The token lives only in your MCP client config and environment. This server does not persist it, so protect that config the way you would any secrets file.