World Anvil MCP Server

MCP (Model Context Protocol) server for interfacing with World Anvil API to assist with D&D world development.

Overview

This MCP server bridges Claude Code with the World Anvil platform, enabling AI-assisted worldbuilding through structured tools, resources, and prompts. Designed specifically for D&D campaign management and creative writing.

Features

Content Management: Articles, blocks, categories, manuscripts
Map Integration: Interactive maps with markers and layers
Campaign Tools: RPG systems, timelines, session notes
D&D Assistance: NPC generation, location design, quest tracking
Notebook System: Organized notes and documentation

Prerequisites

Python 3.11+
uv (fast Python package manager) — https://docs.astral.sh/uv/
World Anvil account with Grandmaster guild membership
World Anvil API application key
World Anvil user authentication token

Installation

# Clone repository and enter it
cd world-anvil

# Recommended: create a local virtualenv with uv
uv venv --python 3.11 .venv

# Activate the environment
# macOS/Linux
source .venv/bin/activate
# Windows (PowerShell)
.venv\\Scripts\\Activate.ps1

# Install dependencies (dev extras optional)
uv pip install -e .[dev]

# Tip: you can also run without activating via uv
uv run world-anvil-mcp

Without uv:

python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\Activate.ps1
pip install -e .[dev]

Configuration

Create a .env file:

WORLD_ANVIL_APP_KEY=your_application_key_here
WORLD_ANVIL_USER_TOKEN=your_user_token_here

Usage

Running the Server

# Start MCP server with stdio transport
world-anvil-mcp

# Or run directly with Python
python -m world_anvil_mcp.server

With Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "world-anvil": {
      "command": "world-anvil-mcp"
    }
  }
}

Documentation

Design Specification - Complete architecture and design
API Reference - Tool and resource documentation
Usage Examples - Common workflows

Project Status

🚧 In Development — Phase 0.4 (Early Implementation)

Architecture and specifications drafted; initial server scaffolding in place.
Quality gates configured (ruff, mypy, pytest); tests being added.
See docs/PHASE_0_STATUS.md for detailed phase tracking and milestones.

License

BSD 3-Clause License — See LICENSE file for details

Resources

Installation

# Clone repository and enter it cd world-anvil # Recommended: create a local virtualenv with uv uv venv --python 3.11 .venv # Activate the environment # macOS/Linux source .venv/bin/activate # Windows (PowerShell) .venv\\Scripts\\Activate.ps1 # Install dependencies (dev extras optional) uv pip install -e .[dev] # Tip: you can also run without activating via uv uv run world-anvil-mcp

Without uv:

python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1 pip install -e .[dev]