foundryvtt

This MCP server integrates FoundryVTT with AI assistants, enabling natural language interactions with your tabletop sessions. It exposes a set of tools to query game data, manage the world state, perform dice rolls, and generate content, all through MCP client prompts. Typical use cases include asking the AI to roll dice with expressions like 2d6+3, search for NPCs in the current scene, retrieve journal entries, check combat initiative, or generate a random NPC merchant. The server also provides world-wide search capabilities and data access via FoundryVTT data endpoints (foundry:// URIs) for direct data access by MCP clients.

To use the tools, connect your MCP client to the server and invoke the available commands. For example, you can request search_actors to locate characters, get_actor_details for specific attributes, search_items for equipment or spells, or roll_dice with a formula. The World section lets you refresh data or view a summary of the current world state, while Game Mechanics includes lookup_rule for rules and spell descriptions. For content creation, you can generate_npc or generate_loot to produce assets on the fly. Diagnostics (when enabled with the REST API module) allows monitoring logs and health metrics.

Prerequisites:

• Node.js 18+ installed on your machine
• Access to a running FoundryVTT server with an active world
• A suitable MCP-compatible AI client

Installation steps:

1. Clone the repository git clone <repository-url>
2. Install dependencies cd foundry-mcp-server npm install
3. Run the interactive setup wizard to detect FoundryVTT and generate configuration npm run setup-wizard
   • The wizard will attempt to locate your FoundryVTT server, test connectivity, and create a .env file with the necessary values.
4. (Optional) Manually configure environment variables Copy .env.example to .env and set: FOUNDRY_URL, FOUNDRY_USERNAME, FOUNDRY_PASSWORD
5. Build and start the server npm run build npm start
6. Verify connectivity Use npm run test-connection or the diagnostics tools once REST API module is enabled

Tips and commonly used guidance:

• The server exposes FoundryVTT data via foundry:// URIs (e.g., foundry://actors, foundry://scenes) for quick data access by MCP clients.
• Diagnostics tools require the REST API module; ensure it is installed and configured if you need get_recent_logs, get_system_health, or diagnose_errors.
• Keep your FoundryVTT URL and credentials secure. Use environment variables to avoid embedding secrets in code.
• If you encounter connection issues, re-run the setup wizard or consult TROUBLESHOOTING.md for common problems and steps.
• The environment supports live world state on connect via Socket.IO; expect a full world state payload when clients establish a connection.