FoundryVTT

You can run a dedicated MCP server that connects FoundryVTT with AI assistants, letting you query game data, roll dice, generate content, and manage your campaign through natural language. This server provides secure, local integration and supports real-time updates for a smoother tabletop experience.

How to use

Start the MCP server as a local process and connect your MCP client (such as Claude Desktop) to it. You will be able to ask your AI helper to roll dice, search actors, items, scenes, and journals, review the current combat and scene state, generate NPCs or loot, and look up game rules. You can also request tactical advice, plot hooks, and world-building content on demand. Use the client to send natural language requests and receive structured results that you can act on within FoundryVTT.

How to install

Prerequisites you need before installing are Node.js version 18 or newer and a running FoundryVTT server that is accessible from the MCP server host. You should also have an MCP-compatible AI client ready to connect.

Choose one of the setup paths below. The interactive setup wizard is the simplest path, but you can also do a manual setup if you prefer.

Quick Setup (Recommended)

git clone <repository-url>
cd foundry-mcp-server
npm install
npm run setup-wizard

Manual Setup

1. Clone and install dependencies.

git clone <repository-url>
cd foundry-mcp-server
npm install

2. Configure environment variables by copying the example and editing as needed.

cp .env.example .env
# Edit .env with your FoundryVTT details

3. Required environment variables (examples shown). Replace with your actual values.

FOUNDRY_URL=http://localhost:30000
FOUNDRY_API_KEY=your_api_key_here
# OR use username/password:
FOUNDRY_USERNAME=your_username
FOUNDRY_PASSWORD=your_password

4. Test the connection, build, and start the server.

npm run test-connection  # Verify setup
npm run build
npm start

Development mode

If you want to run a development workflow for rapid iteration, use the development command.

npm run dev

Additional setup notes

FoundryVTT authentication can be configured in two ways. Use a secure Local REST API module for full local integration, or fall back to a username/password setup if the REST API module is unavailable. The Local REST API option provides full API access and privacy by keeping everything local.

Security and maintenance

Limit FoundryVTT user permissions to the minimum required for MCP operations. Run the MCP server on an internal network when possible and monitor logs for suspicious activity. Prefer API keys for authentication when available.

Diagnostics and troubleshooting

If you run into connectivity or authentication issues, verify that FoundryVTT is reachable at the configured URL and that the correct API key or credentials are in place. Use the built-in diagnostic tools to test the connection and inspect system health.

Available tools

search_actors

Query actors, NPCs, monsters by name or type and apply filters to locate relevant characters in your world.

search_items

Search equipment, spells, consumables, and other items across your world and compendia.

search_journals

Search journal entries, notes, and handouts for quick reference.

get_scene_info

Retrieve details about the current scene, including active tokens, lighting, and scene settings.

get_actor_details

Fetch comprehensive information about a specific actor, including stats and equipment.

roll_dice

Roll dice using any standard RPG formula and return structured results.

update_actor_hp

Modify a character’s hit points to reflect damage or healing.

get_combat_status

Query the current combat state, initiative order, and active combatants.

lookup_rule

Look up game rules, spell descriptions, and mechanical effects.

generate_npc

Create a new non-player character with specified race, level, role, and alignment.

generate_loot

Generate loot appropriate for a given challenge rating or encounter.

roll_table

Roll a predefined table for random encounters, events, or loot.

suggest_tactics

Provide combat tactics and strategic advice based on the current encounter.

get_system_health

Check server health metrics and performance status.

get_recent_logs

Retrieve the most recent log entries for debugging.

diagnose_errors

Analyze recent issues and propose troubleshooting steps.