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:

Go to Configuration → User Management
Click Create User
Set a username (e.g., mcp-api) and a strong password
Assign the Assistant GM role (needed to read world data and roll dice)
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)
`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

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

bunx foundryvtt-mcp test-connection   # Test FoundryVTT connectivity
bunx foundryvtt-mcp setup-wizard      # Re-run interactive setup

Detailed guide: TROUBLESHOOTING.md

Development

bun run build          # Compile TypeScript
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)

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