FoundryVTT MCP Server

A Model Context Protocol (MCP) server that integrates with FoundryVTT, allowing AI assistants to interact with your tabletop gaming sessions through natural language.

Features

• Dice Rolling — standard RPG notation with any formula
• Data Querying — search and inspect actors, items, scenes, journals
• Game State — combat tracking, chat messages, user presence
• Content Generation — NPCs, loot tables, rule lookups
• World Search — full-text search across all game entities
• Live Connection — Socket.IO loads complete world state on connect
• MCP Resources — foundry:// URIs for direct data access
• Diagnostics — optional server health monitoring (requires REST API module)

Quick Start

Prerequisites

• Node.js 18+ (or Bun)
• FoundryVTT server running with an active world
• MCP-compatible AI client (Claude Desktop, Claude Code, VS Code, etc.)

Recommended: Create a Dedicated API User

It is recommended to create a separate FoundryVTT user account for the MCP server rather than using your own GM or player account. This provides better security and auditability.

In FoundryVTT:

1. Go to Configuration → User Management
2. Click Create User
3. Set a username (e.g., mcp-api) and a strong password
4. Assign the Assistant GM role (needed to read world data and roll dice)
5. Use this account's credentials in your MCP configuration

Benefits:

• Chat messages and actions from the MCP server are clearly attributed to a separate user
• You can revoke access by disabling the API user without affecting your own account
• Limits blast radius if credentials are ever exposed

Installation

Run directly without installing — no clone needed:

bunx foundryvtt-mcp

Or with npx:

npx -y foundryvtt-mcp

Client Configuration

Claude Desktop / Claude Code

Add to your MCP configuration (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

VS Code

Add to your VS Code MCP settings:

{
  "servers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

Development Setup

For local development or contributing:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp
bun install
bun run setup-wizard

The setup wizard will detect your FoundryVTT server, test connectivity, and generate your .env configuration.

To configure manually, see the Configuration Guide.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | FOUNDRY_URL | Yes | FoundryVTT server URL (e.g., http://localhost:30000) | | FOUNDRY_USERNAME | Yes | FoundryVTT user account | | FOUNDRY_PASSWORD | Yes | FoundryVTT user password | | FOUNDRY_USER_ID | No | Bypass username-to-ID resolution | | FOUNDRY_API_KEY | No | REST API module key (enables diagnostics tools) | | FOUNDRY_WRITE_ENABLED | No | Enable game-state mutations — true required for the write tools (default: false) | | LOG_LEVEL | No | debug, info, warn, or error (default: info) | | FOUNDRY_TIMEOUT | No | Request timeout in ms (default: 10000) |

Usage

Ask your AI assistant things like:

• "Roll 1d20+5 for an attack roll"
• "Show me all the NPCs in this scene"
• "What's the current combat initiative order?"
• "Search the world for anything related to dragons"
• "Generate a random NPC merchant"

Available Tools

Data Access

• search_actors — find characters, NPCs, monsters
• get_actor_details — detailed character information
• search_items — find equipment, spells, consumables
• get_scene_info — current scene details
• search_journals — search notes and handouts
• get_journal — retrieve a specific journal entry
• get_users — list online users and their status
• get_combat_state — combat state and initiative order
• get_chat_messages — recent chat history

Write Operations (require FOUNDRY_WRITE_ENABLED=true)

Game-state mutations are disabled by default. They use the Socket.IO modifyDocument protocol over an authenticated session, and the connected user needs GM/owner permission. Set FOUNDRY_WRITE_ENABLED=true to enable them.

• next_turn — advance the active combat to the next turn (wraps to the next round)
• end_combat — end (delete) the active combat encounter
• set_initiative — set a combatant's initiative in the active combat
• move_token — move a token to new x/y coordinates on its scene
• apply_status_effect — apply or remove a status condition (e.g. prone, stunned) on a token's actor
• update_actor_attributes — patch an actor's system attributes (HP, currency, spell slots, …)
• create_actor_item — add an inline item to an actor
• update_actor_item — apply a JSON merge patch to an actor's item
• delete_actor_item — remove an item from an actor

World

• search_world — full-text search across all game entities
• get_world_summary — overview of the current world state
• refresh_world_data — reload world data from FoundryVTT

Game Mechanics

• roll_dice — roll dice with any formula
• lookup_rule — game rules and spell descriptions

Content Generation

• generate_npc — create random NPCs
• generate_loot — create treasure appropriate for level

Diagnostics (requires REST API module)

• get_recent_logs — retrieve filtered FoundryVTT logs
• search_logs — search logs with regex patterns
• get_system_health — server performance and health metrics
• diagnose_errors — analyze errors with troubleshooting suggestions
• get_health_status — comprehensive health diagnostics

Available Resources

• foundry://actors — all actors in the world
• foundry://items — all items in the world
• foundry://scenes — all scenes
• foundry://scenes/current — current active scene
• foundry://journals — all journal entries
• foundry://users — online users
• foundry://combat — active combat state
• foundry://world/settings — world and campaign settings
• foundry://system/diagnostics — system diagnostics (requires REST API module)

Troubleshooting

The connectivity and setup helpers ship in the source tree (not the published bin), so run them from a dev checkout:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp && bun install
bun run test-connection   # Probe FoundryVTT connectivity
bun run setup-wizard      # Re-run interactive setup

Detailed guide: TROUBLESHOOTING.md

Development

bun run build          # Compile TypeScript and make dist/index.js executable
bun run dev            # Development mode with hot reload
bun test               # Unit tests (Vitest)
bun run test:e2e       # E2E tests (Playwright)
bun run lint           # Lint code (Biome)
bun run smoke          # Startup smoke test against the local build
bun run smoke:pack     # Pack-and-install smoke test (mirrors what npx consumers get)

See Development Guide for project structure, adding tools, testing, and building.

Roadmap

See Feature Tracker for completed and planned features.

Contributing

See CONTRIBUTING.md.

License

MIT License — see LICENSE for details.

Support

• Issues: GitHub Issues
• Discord: FoundryVTT Discord #api-development
• Docs: FoundryVTT API

Acknowledgments

• FoundryVTT team for the excellent VTT platform
• Anthropic for the Model Context Protocol
• The tabletop gaming community for inspiration and feedback