{
  "markdown": "# @excaliwow/mcp\n\nThe Excaliwow **Model Context Protocol** server — lets an AI agent create, read,\nrender, manage, and edit diagrams in your Excaliwow account through the same\npublic REST API (`/api/v1`) the CLI uses. It runs over **stdio**, so any MCP\nclient (Claude Desktop, Claude Code, etc.) can launch it with `npx`.\n\nThe public [`excaliwow/mcp`](https://github.com/excaliwow/mcp) repository contains\ndistribution metadata and documentation for this package; the hosted application\nsource is not published there.\n\n## Install\n\nFirst mint a Personal Access Token at https://excaliwow.com/app/settings\n(Settings → Developer / API tokens) with **`read` + `write`** capabilities —\nenough for sixteen of the eighteen tools. Add **`delete`** only if you want the agent\nto trash and restore diagrams (see [Security notes](#security-notes)). Pass it as\n`EXCALIWOW_TOKEN`.\n\n### Claude Code (CLI)\n\nOne command. `--scope local` stores the server in your own settings, so the\ntoken never lands in a file you might commit. Export the token first so the\nliteral PAT never lands in your shell history — `--env NAME=\"$NAME\"` passes\nthe value through without typing it a second time on the command line:\n\n```sh\nexport EXCALIWOW_TOKEN=excw_pat_…\nclaude mcp add excaliwow --scope local \\\n  --env EXCALIWOW_TOKEN=\"$EXCALIWOW_TOKEN\" \\\n  -- npx -y @excaliwow/mcp\n```\n\n### Claude Desktop (and other JSON-config clients)\n\nAdd it to your client's config file (e.g. Claude Desktop's\n`claude_desktop_config.json`, or your client's MCP settings — see your client's\nMCP setup docs). The spec is unversioned, so `npx -y` always launches the latest\nrelease — you pick up new tools and fixes automatically, with nothing to bump:\n\n```json\n{\n  \"mcpServers\": {\n    \"excaliwow\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@excaliwow/mcp\"],\n      \"env\": {\n        \"EXCALIWOW_TOKEN\": \"excw_pat_…\"\n      }\n    }\n  }\n}\n```\n\nThe server reads `EXCALIWOW_TOKEN` per call from the environment (or, if you also\nuse `@excaliwow/cli` and have run `excaliwow auth login`, that stored login) and\nnever writes the token to disk itself.\n\n## Troubleshooting\n\n**\"Not authenticated\" / 401 / the agent's tool calls fail.** The server starts\neven without a token (so it can list its tools), so a missing or invalid\n`EXCALIWOW_TOKEN` only surfaces when the agent first calls a tool. Starting with\nno token prints a one-line `EXCALIWOW_TOKEN is not set` warning to **stderr**. To\ncheck a token directly, run the health probe — it makes one authenticated read\nand prints a clear verdict (`ok`, `401 — token is invalid or expired`, or\n`could not reach <url>` when the API itself is unreachable) and exits with a\nmatching code (0 ok, 1 missing/invalid token, 2 unreachable):\n\n```sh\nnpx -y @excaliwow/mcp --health\n```\n\n### CLI flags\n\n| Flag        | Effect                                                                                        |\n| ----------- | --------------------------------------------------------------------------------------------- |\n| `--health`  | Check the token + API reachability, then exit (0 ok, 1 missing/invalid token, 2 unreachable). |\n| `--version` | Print the installed version and exit.                                                         |\n| `--help`    | Print usage (flags + env vars) and exit.                                                      |\n\n## Tools\n\nEighteen tools, scoped to safe agent use:\n\n| Tool                     | Capability | What it does                                                                                                           |\n| ------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------- |\n| `generate_diagram`       | `write`    | Create a diagram from the high-level node/edge DSL (auto-laid-out); returns the editor URL. Best for quick flowcharts. |\n| `create_scene`           | `write`    | Create a **rich, hand-authored** diagram from a raw Excalidraw scene — full control of layout, style, and typography.  |\n| `read_diagram`           | `read`     | Compact summary (title + per-type counts) **plus** a rendered PNG; opt into `includeGeometry` for a bounds list.       |\n| `get_scene`              | `read`     | Return a diagram's full raw scene (`{ elements, appState }`) for editing — read → mutate → `regenerate_diagram`.       |\n| `export_diagram`         | `read`     | Render to full-fidelity bytes to **save** (png base64, or svg as raw text) — the bytes to keep, not a vision image.    |\n| `list_diagrams`          | `read`     | Page through your diagrams (`filter: active \\| trash`).                                                                |\n| `move_diagram`           | `write`    | Move a diagram to a folder (or to root).                                                                               |\n| `edit_diagram`           | `write`    | Additively merge a DSL fragment (add nodes/edges, update node style/label).                                            |\n| `regenerate_diagram`     | `write`    | Replace a diagram's contents in place — from a fresh `spec` (re-layout) **or** a raw `scene`, same id.                 |\n| `trash_diagram`          | `delete`   | Soft-delete a diagram to trash. **Reversible** (see `restore_diagram`).                                                |\n| `restore_diagram`        | `delete`   | Restore a trashed diagram, reopening it at its original id and URL.                                                    |\n| `lint_diagram`           | `read`     | Check a diagram for overlaps, clipped labels, out-of-frame elements, and low-contrast text.                            |\n| `patch_elements`         | `write`    | Apply element-addressable deltas (add/update/move/resize/restyle/delete) in place — the cheapest edit path.            |\n| `generate_from_template` | `write`    | Create a diagram from a named layout template (`swimlane`, `layered-stack`, `matrix`, `container-with-children`).      |\n| `list_icons`             | `read`     | List the curated icons you can embed via an `image` element + `icon-<name>` fileId (id + label + category).            |\n| `list_folders`           | `read`     | List the caller's folders (id + name + parentId) to resolve or discover a `folderId`.                                  |\n| `create_folder`          | `write`    | Create a folder (optionally nested under a `parentId`) to organize diagrams.                                           |\n| `rename_diagram`         | `write`    | Change only a diagram's title, leaving its contents and id/url untouched.                                              |\n\n`read_diagram` returns a summary + image, **never** the raw scene JSON, to keep\ncontext small. Pass `includeGeometry: true` to additionally get a compact,\nbounded `{ id, type, label, x, y, w, h }` list (top-left x/y) so the agent can\n**detect** label/box collisions or misplaced nodes programmatically instead of\neyeballing the PNG — it is derived from the scene, so it is present even when the\nrender fails, and it is a small fixed-field summary, not the raw element dump.\nPass `includeScene: 'compact'` instead for a bounded, element-addressable\nprojection — a superset of the geometry fields that also carries style, text,\nand container/binding refs (≤17 fields/element) — the read half of the\n`read_diagram` → `patch_elements` surgical-edit loop.\n`export_diagram` returns the rendered **bytes** to save to a file — png as\nbase64, svg as raw text — distinct from `read_diagram`, which returns an image\nblock for a vision model to look at. An MCP server runs over stdio and cannot\nwrite to your repo, so a client with filesystem access (e.g. Claude Code) decodes\nand saves the bytes itself. Or skip the round-trip through the model and stream\nstraight to disk with the CLI: `excaliwow diagrams render <id> -o\ndocs/architecture.png` (or `.svg`) — also the fallback when a render is too large\nto return inline.\n\n`trash_diagram` / `restore_diagram` are a **reversible** pair\ngated on the `delete` capability — registered always, they return a clean\n`insufficient_scope` error (changing nothing) unless the token carries `delete`,\nso a `read` + `write` token can't trash anything. Hard-delete/purge and making a\ndiagram publicly shareable are deliberately **not** agent tools — those are\nirreversible, so a misled agent can't destroy or expose your diagram. Purge or\npublish from the dashboard or the CLI.\n\n### Two authoring paths\n\n`generate_diagram` takes the high-level node/edge **DSL** and auto-lays it out —\nreach for it when you just want a quick flowchart. `create_scene` takes a **raw,\nhand-authored Excalidraw scene**, so the agent controls every element's position,\nsize, color, stroke, fill, typography, and connections — the path for rich,\npolished, custom diagrams. You author elements _tersely_ (id, type, geometry,\ntext, colors) and the Excalidraw boilerplate is filled in for you; a\nfully-specified element (or a pasted `.excalidraw` scene) is passed through\nunchanged. To iterate on a rich diagram: `get_scene` → edit the elements →\n`regenerate_diagram` with the edited `scene`.\n\n### Discovery resources\n\nThe DSL grammar + a worked example are embedded in the `generate_diagram` tool\ndescription, with the full reference served as an MCP resource at\n**`excaliwow://dsl/reference`**. The rich-scene authoring primer + a worked\nexample ride in the `create_scene` description, with the full guide (every\nelement type, all styling props, bindings, groups, frames, palette, and\nlayout/beauty heuristics) at **`excaliwow://scene/authoring`**.\n\n## Environment variables\n\n| Var                 | Effect                                                                                      |\n| ------------------- | ------------------------------------------------------------------------------------------- |\n| `EXCALIWOW_TOKEN`   | **Required** (standalone). Bearer PAT; read per call, never written to disk by this server. |\n| `EXCALIWOW_API_URL` | API origin. Default `https://excaliwow.com`; normally leave unset.                          |\n\n## Requirements\n\nNode **>= 22.11.0**. This is a support-policy floor, not a technical one —\nnothing shipped here uses a Node-22-only API (the code's newest runtime\ndependency is global `fetch`, available since Node 18); the floor tracks\n\"current LTS\" so `npx -y @excaliwow/mcp` runs on a Node build we actually test\nagainst, and matches `@excaliwow/cli`'s floor. If your MCP client is stuck on\nan older Node and `npx` refuses to run this server, that refusal is\nintentional — upgrade Node rather than treat it as a bug.\n\n## Security notes\n\n- **Keep the token out of anything you commit.** A project-scoped config that\n  lives in the repo (a committed `.mcp.json`, or `claude mcp add --scope\nproject`) puts the token into git history. Use a user- or local-scoped config\n  (`--scope local`), or reference an environment variable instead of pasting the\n  literal token.\n- **Typing the literal token on a command line puts it in your shell history**\n  (`~/.zsh_history`, `~/.bash_history`, …) and briefly in the process list.\n  `export EXCALIWOW_TOKEN=…` once, then pass it through with `--env\nEXCALIWOW_TOKEN=\"$EXCALIWOW_TOKEN\"` (or pull it from a secrets manager) instead\n  of pasting the PAT into the `claude mcp add` command itself.\n- **Mint with `read` + `write` (add `delete` only if you want trash/restore).**\n  Sixteen of the eighteen tools need just `read` + `write`; a `read` + `write` PAT can\n  neither expose your diagrams publicly nor delete them, even if the agent is\n  misled (`trash_diagram` / `restore_diagram` simply return `insufficient_scope`\n  and do nothing). Add the `delete` capability only if you want the agent to be\n  able to soft-delete and restore — it's reversible, but it's still a capability\n  to grant deliberately. Pick capabilities specifically rather than the coarse\n  `read-write` preset, which additionally grants `publish` (and `delete`).\n- The token is a credential to your account. It lives only in your MCP client\n  config / environment; this server does not persist it. Treat that config the\n  way you'd treat any secrets file.\n\n## Support\n\nFound a bug or have a question? See [excaliwow.com/docs/mcp](https://excaliwow.com/docs/mcp)\nor reach us at [excaliwow.com/contact](https://excaliwow.com/contact).\n\n## License\n\nApache-2.0 — see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).\n",
  "bytes": 12427,
  "sha": "7b8f0e31941fb0dfa5b351404468a8f892bbf58007e154bef073b4f7133da90c",
  "repo_slug": "excaliwow/mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_excaliwow_mcp_0ad2181c/readme"
}