World Anvil MCP Server

A Model Context Protocol (MCP) server written in Go that provides tools for interacting with World Anvil's campaign management platform. This server enables AI assistants like Claude to search and retrieve campaign data, NPCs, locations, items, and other worldbuilding content from your World Anvil worlds.

Features

• Search Articles: Search for articles by title or content across your World Anvil world
• Get Article by ID: Retrieve specific articles by their unique identifier
• List Articles by Category: Browse articles filtered by category (creatures, locations, npcs, etc.)
• Get Article Details: Fetch complete article information including content and metadata

Prerequisites

• Go 1.23 or higher
• A World Anvil account with API access
• World Anvil API key and application key (see below)

Quick Start

# Clone the repository
git clone https://github.com/yourusername/worldanvil-mcp-server.git
cd worldanvil-mcp-server

# Install dependencies
go mod download

# Copy environment template and configure
cp .env.example .env
# Edit .env with your World Anvil credentials

# Build the project
make build
# Or: go build -o worldanvil-mcp-server main.go

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Add your World Anvil API credentials to .env:

# Get your API key from: https://www.worldanvil.com/api/auth/key
WORLD_ANVIL_API_KEY=your_api_key_here

# Your World Anvil world ID (found in URL: worldanvil.com/w/YOUR_WORLD_ID)
WORLD_ANVIL_WORLD_ID=your_world_id

# Application key (required for Boromir API v2)
# Apply at: https://docs.google.com/forms/d/e/1FAIpQLSduBh_rzrFwl4dM8lLVGtnfGwVf5FKm0sJv0KtM-pCMJY77RA/viewform
WORLD_ANVIL_APPLICATION_KEY=your_application_key_here

# API URL (uses Boromir v2 API)
WORLD_ANVIL_API_URL=https://www.worldanvil.com/api/external/boromir

Getting Your API Key

1. Log in to World Anvil
2. Go to your Account Settings
3. Navigate to the API section
4. Generate a new API key if you don't have one
5. Copy the key to your .env file

Finding Your World ID

Your World ID can be found in the URL when viewing your world: https://www.worldanvil.com/w/[YOUR_WORLD_ID]

Usage

Running Locally

The server supports two transport modes:

HTTP mode (recommended - easiest for Docker/containers):

# Run on localhost
./worldanvil-mcp-server -http :8080

# Or in development
go run main.go -http localhost:8080

# Test the server
curl http://localhost:8080

# Or with Docker
docker-compose up -d

Stdio mode (for VS Code/Claude Desktop native integration):

./worldanvil-mcp-server
# Or: make run

Using with MCP Clients

Option 1: HTTP Mode (Docker/Containerized)

Start the server:

docker-compose up -d
# Server runs on http://localhost:8080

Configure your MCP client:

{
  "mcpServers": {
    "worldanvil": {
      "url": "http://localhost:8080"
    }
  }
}

Option 2: Stdio Mode (Claude Desktop/VS Code)

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "worldanvil": {
      "command": "/absolute/path/to/worldanvil-mcp-server"
    }
  }
}

For VS Code, see .vscode/mcp.json for an example configuration.

Available Tools

search_articles

Search for articles by title or content.

Parameters:

• query (string, required): Search term to look for
• limit (number, optional): Maximum number of results (default:

... View full README on GitHub