FoundryVTT

You set up a dedicated MCP (Model Context Protocol) server that connects with FoundryVTT so your AI assistants can query game data, roll dice, generate content, and manage your session in real time. This lets you run immersive, AI-assisted tabletop campaigns with secure, local control over your FoundryVTT world.

How to use

You interact with the MCP server through an MCP client or integration that supports the protocol. Start the server locally and point your client to the available connection methods. Use the server to perform data queries (actors, items, scenes, journals), roll dice with standard RPG notation, access game state (current scene, combat, world data), and request content generation (NPCs, loot, encounters). For advanced play, look up rules and explore tactical or world-building suggestions generated by the AI assistant. Ensure your FoundryVTT user permissions align with the actions you want the assistant to perform, such as creating journal entries or modifying content.

How to install

Prerequisites you need before installing the MCP server are Node.js version 18 or later and a FoundryVTT server already running and accessible on your network. You also need an MCP-compatible AI client to connect to the server.

Step-by-step setup

npm run setup-wizard

# If you prefer manual steps instead of the wizard, follow these steps after cloning:
# 1) Install dependencies and build
# 2) Start the server

# Interactive wizard steps shown here are executed in your terminal to detect FoundryVTT and generate .env

# Final start (used by the stdio config):
npm start

After setup start

Once the server is installed and started, keep it running in the background or in a dedicated terminal session. Your MCP client will connect to the server using the configured environment variables and the start command defined in your setup.

How to install (detailed)

Follow these concrete commands to set up the MCP server on your machine.

Configuration and security

Configure environment variables to connect to FoundryVTT and secure the MCP server. The following variables are used in typical setups. Use meaningful values in your environment file.

Diagnostics and troubleshooting

If you encounter connection issues, verify that FoundryVTT is running on the expected URL and port, confirm your API key or username/password, and ensure the necessary permissions are granted to the FoundryVTT user. Check server logs for errors and run internal health checks as needed.

Development notes

Development flow and testing are documented in the project’s development scripts. Use the standard npm commands to build, test, and run the development server while making changes.

How to configure your MCP client (example)

{
  "mcpServers": {
    "foundry": {
      "type": "stdio",
      "name": "foundry_mcp",
      "command": "npm",
      "args": ["start"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_API_KEY": "your_api_key_here",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

Available resources and tools (reference)

This server exposes a range of data access, game mechanics, content generation, and diagnostics capabilities. You can query actors, items, journals, and scenes; roll dice; manage combat; generate NPCs and loot; look up rules; and monitor system health.

Notes

Keep your environment secure by using API keys where possible, restricting FoundryVTT user permissions to the minimum needed, and running the server on an internal network. Regularly review logs for unusual activity and perform health checks to ensure stable operation.

Available tools

search_actors

Query actors, NPCs, monsters, or characters by name, type, or other attributes.

search_items

Find equipment, spells, consumables, and other items in inventories or compendiums.

search_journals

Search journal entries and handouts across the world.

get_scene_info

Retrieve details about the current scene, including environment, lighting, and active elements.

get_actor_details

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

roll_dice

Roll dice using standard RPG notation or custom formulas.

update_actor_hp

Modify a character's hit points during play.

get_combat_status

Obtain the current combat state, order of initiative, and active combatants.

lookup_rule

Look up game rules, spells, and mechanical descriptions.

generate_npc

Create a new non-player character with specified traits.

generate_loot

Create treasure appropriate for a given challenge rating or level.

roll_table

Roll on a random table to generate encounters, events, or rewards.

suggest_tactics

Provide tactical advice for combat scenarios.

generate_location

Create a new location or locale description for world-building.