worldanvil-mcp-server

MCP server for World Anvil: browse, search, and manage a world's content, and export a complete copy for migrations or backups. 18 focused tools.

Unofficial community project, not affiliated with World Anvil. Requires Node 18+.

Tools

Group	Tools
Navigate	list_worlds, get_world, get_identity, list_categories
Articles	list_articles (all pages, category/type filters), search_articles (title/slug/tags), get_article (full BBCode content + template fields)
Assets	list_assets (secrets, maps, timelines, histories, notebooks, subscribergroups), get_asset (maps/notebooks include their full hierarchy)
Search	search_content (full-text across articles, secrets, notes), find_references (backlinks to an article)
Export	export_world (raw JSON tree + image binaries + id→slug index, to disk)
Write	create_article (defaults private+draft), update_article, delete_article, create_category, update_category, delete_category

Setup

npm install
npm run build

Credentials

Both from worldanvil.com → profile picture → User API Tokens:

• WA_AUTH_TOKEN — your personal API token
• WA_APPLICATION_KEY — via the Application Key Form on the same page (manually approved by World Anvil).

Alternatively, WA_API_BASE_URL can point at a proxy that injects an application key (instead of WA_APPLICATION_KEY). Only use a proxy you run or trust — your auth token, which grants full API access to your account, transits it on every request.

Claude Code

claude mcp add --scope user worldanvil \
  -e WA_AUTH_TOKEN=your-token \
  -e WA_APPLICATION_KEY=your-app-key \
  -- node /absolute/path/to/worldanvil-mcp/dist/index.js

Claude Desktop

Add to the config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

"worldanvil": {
  "command": "node",
  "args": ["/absolute/path/to/worldanvil-mcp/dist/index.js"],
  "env": {
    "WA_AUTH_TOKEN": "your-token",
    "WA_APPLICATION_KEY": "your-app-key"
  }
}

Behavior worth knowing

• Content search uses a local cache. The first search_content/find_references call on a world fetches every article body (about a minute for a few hundred articles); after that, every call re-syncs only what changed. The cache lives in ~/.cache/worldanvil-mcp/ (%LOCALAPPDATA%\worldanvil-mcp\cache on Windows), is only a search index, and is safe to delete — it rebuilds itself.
• Article content is World Anvil BBCode. Links between entities appear as @[Title](type:uuid) mentions; find_references searches for the uuid, so backlinks are exact.
• Exports are raw and honest. export_world writes untouched API payloads, one file per entity, plus entities.json (id → {kind, title, slug, file}) for rewriting mention links during a migration. Anything it could not fetch or resolve is listed in manifest.json — never silently dropped. It refuses to write into a directory that isn't empty or a previous export.
• Upstream API limitations (World Anvil's side, all surfaced in tool output): image endpoints currently return errors, so embedded [img:id] references may be unresolvable; marker listings on private maps return 403 even for the map's owner (set a map public temporarily to read its markers); article comments are not exposed by the API at all.

Development

npm run dev                             # run from source
node scripts/smoke.mjs                  # MCP handshake + tool list
node scripts/smoke.mjs <tool> '<json>'  # call one tool (WA_* env vars required)