A Model Context Protocol (MCP) server that integrates with FoundryVTT, allowing AI assistants to interact with your tabletop gaming sessions. Query actors, roll dice, generate content, and manage your game world through natural language.
Interactive Setup Wizard:
git clone <repository-url>
cd foundry-mcp-server
npm install
npm run setup-wizard
The setup wizard will:
.env configuration filegit clone <repository-url>
cd foundry-mcp-server
npm install
cp .env.example .env
# Edit .env with your FoundryVTT details
FOUNDRY_URL=http://localhost:30000
FOUNDRY_USERNAME=your_username
FOUNDRY_PASSWORD=your_password
npm run test-connection # Verify setup
npm run build
npm start
npm run dev
The MCP server connects to FoundryVTT via Socket.IO using a standard FoundryVTT user account. No custom modules are required for full game data access.
.env file:FOUNDRY_URL=http://localhost:30000
FOUNDRY_USERNAME=your_username
FOUNDRY_PASSWORD=your_password
The server authenticates via a 4-step Socket.IO flow:
/join page to obtain a session cookieFOUNDRY_USER_ID if set)joinGame with credentials to receive the complete world stateInstalling the Foundry Local REST API module adds 5 server monitoring tools (get_recent_logs, search_logs, get_system_health, diagnose_errors, get_health_status):
https://github.com/laurigates/foundryvtt-mcp/releases/latest/download/module.json.env:FOUNDRY_API_KEY=your_api_key_here
Your FoundryVTT user needs these permissions:
Ask your AI assistant things like:
Dice Rolling:
Game Data:
Content Generation:
World Search:
search_actors - Find characters, NPCs, monstersget_actor_details - Detailed character informationsearch_items - Find equipment, spells, consumablesget_scene_info - Current scene detailssearch_journals - Search notes and handoutsget_journal - Retrieve a specific journal entryget_users - List online users and their statusget_combat_state - Combat state and initiative orderget_chat_messages - Recent chat historysearch_world - Full-text search across all game entitiesget_world_summary - Overview of the current world staterefresh_world_data - Reload world data from FoundryVTTroll_dice - Roll dice with any formulalookup_rule - Game rules and spell descriptionsgenerate_npc - Create random NPCsgenerate_loot - Create treasure appropriate for levelget_recent_logs - Retrieve filtered FoundryVTT logssearch_logs - Search logs with regex patternsget_system_health - Server performance and health metricsdiagnose_errors - Analyze errors with troubleshooting suggestionsget_health_status - Comprehensive health diagnosticsThe server exposes these FoundryVTT resources:
foundry://actors - All actors in the worldfoundry://items - All items in the worldfoundry://scenes - All scenesfoundry://scenes/current - Current active scenefoundry://journals - All journal entriesfoundry://users - Online usersfoundry://combat - Active combat statefoundry://world/settings - World and campaign settingsfoundry://system/diagnostics - System diagnostics (requires REST API module)Edit .env to customize:
# Logging
LOG_LEVEL=info # debug, info, warn, error
# Performance
FOUNDRY_TIMEOUT=10000 # Request timeout (ms)
FOUNDRY_RETRY_ATTEMPTS=3 # Retry failed requests
The server includes diagnostic tools to help troubleshoot connection and performance issues:
Connection Testing:
# Test complete MCP connection and functionality
npm run test-connection
# Clean build and test setup
npm run setup
Diagnostic Tools (via AI assistant):
# Test FoundryVTT is accessible
curl http://localhost:30000
# Check server logs
npm run dev # Shows detailed logging
"Failed to connect to FoundryVTT"
"Authentication failed"
FOUNDRY_USER_ID to the 16-character document _id"Tool not found" errors
src/
├── config/ # Zod-validated configuration
├── foundry/
│ ├── auth.ts # Socket.IO 4-step authentication
│ ├── client.ts # FoundryVTT client with worldData cache
│ └── types.ts # TypeScript interfaces + WorldData
├── tools/
│ ├── definitions.ts # Tool schemas by category
│ ├── router.ts # Tool request routing
│ ├── resources.ts # MCP resource definitions
│ └── handlers/ # Per-tool handler implementations
├── diagnostics/ # Optional REST API diagnostics
├── utils/ # Logger, cache utilities
└── index.ts # MCP server entry point
src/tools/definitions.tssrc/tools/handlers/src/tools/router.tssrc/foundry/types.ts if needed# Run tests
npm test
# Run with coverage
npm run test:coverage
# Lint code
npm run lint
# Development build
npm run build
# Clean build
npm run clean && npm run build
| Variable | Required | Description | Default |
|---|---|---|---|
FOUNDRY_URL |
Yes | FoundryVTT server URL | - |
FOUNDRY_USERNAME |
Yes | FoundryVTT username | - |
FOUNDRY_PASSWORD |
Yes | FoundryVTT password | - |
FOUNDRY_USER_ID |
No | 16-char document _id (bypasses username resolution) |
- |
FOUNDRY_API_KEY |
No | REST API module key (enables diagnostics) | - |
LOG_LEVEL |
No | Logging verbosity | info |
NODE_ENV |
No | Environment mode | development |
FOUNDRY_TIMEOUT |
No | Request timeout (ms) | 10000 |
FOUNDRY_RETRY_ATTEMPTS |
No | Retry failed requests | 3 |
FOUNDRY_RETRY_DELAY |
No | Delay between retries (ms) | 1000 |
CACHE_ENABLED |
No | Enable response caching | true |
CACHE_TTL_SECONDS |
No | Cache duration (seconds) | 300 |
CACHE_MAX_SIZE |
No | Maximum cache entries | - |
{
"formula": "1d20+5",
"reason": "Attack roll against goblin"
}
{
"query": "dragon",
"limit": 10
}
{}
{
"query": "goblin",
"type": "npc",
"limit": 10
}
Add to your Claude Desktop MCP settings:
{
"mcpServers": {
"foundry": {
"command": "node",
"args": ["/path/to/foundry-mcp-server/dist/index.js"],
"env": {
"FOUNDRY_URL": "http://localhost:30000",
"FOUNDRY_USERNAME": "your_username",
"FOUNDRY_PASSWORD": "your_password"
}
}
}
}
To enable optional diagnostics tools, add FOUNDRY_API_KEY to the env block:
{
"FOUNDRY_API_KEY": "your_api_key_here"
}
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
const transport = new StdioClientTransport({
command: "node",
args: ["./dist/index.js"],
});
const client = new Client(
{
name: "foundry-client",
version: "1.0.0",
},
{
capabilities: {},
},
);
await client.connect(transport);
// Roll dice
const result = await client.request({
method: "tools/call",
params: {
name: "roll_dice",
arguments: {
formula: "1d20+5",
reason: "Initiative roll",
},
},
});
Complete API documentation is available in the docs/ directory, auto-generated from TypeScript source code and JSDoc comments.
Local development:
npm run docs # Generate documentation
npm run docs:serve # Generate and serve locally
Online: Browse the docs/ folder in this repository or visit the GitHub Pages site (if enabled).
The documentation is automatically updated via GitHub Actions when source code changes.
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featureMIT License - see LICENSE file for details.
npm run test-connection # Test FoundryVTT connectivity
npm run setup-wizard # Re-run interactive setup
Use the get_health_status MCP tool for comprehensive diagnostics (requires REST API module), or check server logs during startup for detailed status information.
Detailed troubleshooting guide: TROUBLESHOOTING.md