# 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
```bash
# 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:
```bash
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -e .[dev]
```
## Configuration
Create a `.env` file:
```env
WORLD_ANVIL_APP_KEY=your_application_key_here
WORLD_ANVIL_USER_TOKEN=your_user_token_here
```
## Usage
### Running the Server
```bash
# 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:
```json
{
"mcpServers": {
"world-anvil": {
"command": "world-anvil-mcp"
}
}
}
```
## Documentation
- [Design Specification](claudedocs/DESIGN_SPECIFICATION.md) - Complete architecture and design
- [API Reference](claudedocs/API_REFERENCE.md) - Tool and resource documentation
- [Usage Examples](claudedocs/USAGE_EXAMPLES.md) - 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
- [World Anvil API Documentation](https://www.worldanvil.com/api/external/boromir/documentation)
- [Model Context Protocol](https://modelcontextprotocol.io)
