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_API_KEY=your_api_key_here
# OR use username/password:
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 supports two secure, local-only authentication methods:
Benefits:
Setup:
https://github.com/laurigates/foundryvtt-mcp/releases/latest/download/module.json.env file:FOUNDRY_URL=http://localhost:30000
FOUNDRY_API_KEY=your_local_api_key_here
Use when: Local REST API module is not available or for simple setups.
Limitations: Some advanced features may not work properly.
.env file:FOUNDRY_URL=http://localhost:30000
FOUNDRY_USERNAME=your_username
FOUNDRY_PASSWORD=your_password
| Feature | Local REST API Module | Username/Password |
|---|---|---|
| Privacy | ✅ 100% Local | ✅ 100% Local |
| Security | ✅ API Key auth | ⚠️ Password auth |
| Performance | ✅ Direct API access | ⚠️ WebSocket only |
| Features | ✅ Complete API access | ❌ Limited functionality |
| Setup | ⚠️ Module install required | ✅ Simple credentials |
| Reliability | ✅ Stable API | ⚠️ Connection dependent |
Your FoundryVTT user needs these permissions:
Ask your AI assistant things like:
Dice Rolling:
Game Data:
Content Generation:
Rule Lookups:
Tactical Advice:
World Building:
search_actors - Find characters, NPCs, monsterssearch_items - Find equipment, spells, consumablessearch_journals - Search notes and handoutsget_scene_info - Current scene detailsget_actor_details - Detailed character informationroll_dice - Roll dice with any formulaupdate_actor_hp - Modify character healthget_combat_status - Combat state and initiativelookup_rule - Game rules and spell descriptionsgenerate_npc - Create random NPCsgenerate_loot - Create treasure appropriate for levelroll_table - Random encounters, events, weathersuggest_tactics - Combat advice and strategyget_system_health - Server performance and health metricsget_recent_logs - Retrieve filtered FoundryVTT logssearch_logs - Search logs with regex patternsdiagnose_errors - Analyze errors with troubleshooting suggestionsThe server exposes these FoundryVTT resources:
foundry://world/info - World and campaign informationfoundry://world/actors - All actors in the worldfoundry://scene/current - Current active scenefoundry://combat/current - Active combat statefoundry://compendium/spells - Spell databasefoundry://compendium/monsters - Monster databaseEdit .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
CACHE_TTL_SECONDS=300 # Cache data for 5 minutes
The server includes comprehensive 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):
When using the Local REST API module, you get access to advanced diagnostic features:
# Test FoundryVTT connection
curl http://localhost:30000/api/status
# Check server logs
npm run dev # Shows detailed logging
"Failed to connect to FoundryVTT"
"Authentication failed"
"Tool not found" errors
src/
├── config/ # Configuration management
├── foundry/ # FoundryVTT client and types
├── tools/ # MCP tool definitions
├── resources/ # MCP resource definitions
├── utils/ # Utilities and logging
└── index.ts # Main server entry point
src/tools/index.tssrc/index.tssrc/foundry/client.tssrc/foundry/types.ts# 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 |
✅ | FoundryVTT server URL | - |
FOUNDRY_API_KEY |
⭐ | API key for authentication | - |
FOUNDRY_USERNAME |
⭐ | Username (if no API key) | - |
FOUNDRY_PASSWORD |
⭐ | Password (if no API key) | - |
LOG_LEVEL |
❌ | Logging verbosity | info |
NODE_ENV |
❌ | Environment mode | development |
FOUNDRY_TIMEOUT |
❌ | Request timeout (ms) | 10000 |
FOUNDRY_RETRY_ATTEMPTS |
❌ | Retry failed requests | 3 |
CACHE_TTL_SECONDS |
❌ | Cache duration | 300 |
⭐ Either API key OR username/password required
{
"formula": "1d20+5",
"reason": "Attack roll against goblin"
}
{
"query": "goblin",
"type": "npc",
"limit": 10
}
{
"race": "human",
"level": 5,
"role": "merchant",
"alignment": "neutral good"
}
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_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, or check server logs during startup for detailed status information.
.env📖 Detailed troubleshooting guide: TROUBLESHOOTING.md
Happy Gaming! 🎲