Provides community support through the FoundryVTT Discord server's #api-development channel
Used for configuration management of the MCP server through environment variables
Used for installation (cloning repository), issue tracking for bugs and feature requests, and contributing through pull requests
Automatically updates documentation when source code changes
Mentioned as a potential hosting option for the server's documentation
Serves as the runtime environment for the MCP server, required as a prerequisite (v18+) for running the FoundryVTT MCP server
FoundryVTT MCP Server
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.
Features
Core Functionality
- 🎲 Dice Rolling - Roll dice with standard RPG notation
- 🔍 Data Querying - Search actors, items, scenes, and journal entries
- 📊 Game State - Access current scene, combat status, and world information
- 🎭 Content Generation - Generate NPCs, loot, and random encounters
- 📝 Rule Lookup - Query game rules and mechanical information
Real-time Integration
- 🔄 Live Updates - WebSocket connection for real-time game state
- ⚔️ Combat Management - Track initiative and combat state
- 👥 User Awareness - See who's online and their status
AI-Powered Features
- 🧠 Tactical Suggestions - Get combat advice and strategy tips
- 🎪 Story Assistance - Generate plot hooks and narrative elements
- 🎨 World Building - Create locations, NPCs, and quests on demand
Installation
Prerequisites
- Node.js 18+
- FoundryVTT server running and accessible
- MCP-compatible AI client (Claude Desktop, etc.)
Quick Setup (Recommended)
🧙♂️ Interactive Setup Wizard:
The setup wizard will:
- Automatically detect your FoundryVTT server
- Test connectivity and authentication
- Generate your
.env
configuration file - Validate the complete setup
Manual Setup
- Clone and install:
- Configure environment:
- Required environment variables:
- Test and start:
Development Mode
FoundryVTT Configuration
The MCP server supports two secure, local-only authentication methods:
Option 1: Local REST API Module (🔒 Recommended)
Benefits:
- ✅ 100% Local - No external dependencies or third-party services
- ✅ Maximum Privacy - Your game data never leaves your network
- ✅ Full Control - You own and manage all authentication
- ✅ Better Performance - Direct local API access
- ✅ Complete API Access - Full access to all FoundryVTT features
Setup:
- Install the Foundry Local REST API module:
- In FoundryVTT: Setup → Add-on Modules → Install Module
- Paste:
https://github.com/laurigates/foundryvtt-mcp/releases/latest/download/module.json
- Enable the module in your world
- Go to Settings → Configure Settings → Module Settings
- Find "Foundry Local REST API" and check "Enable REST API"
- Copy the generated API Key
- Add to your
.env
file:
Option 2: Username/Password (Fallback)
Use when: Local REST API module is not available or for simple setups.
Limitations: Some advanced features may not work properly.
- Ensure your FoundryVTT user has appropriate permissions
- Add credentials to
.env
file:
Comparison Table
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 |
Required Permissions (All Methods)
Your FoundryVTT user needs these permissions:
- View actors, items, scenes, and journals
- Create and modify journal entries (for content generation)
- Access compendium data
- Use dice rolling API
Usage
Basic Queries
Ask your AI assistant things like:
Dice Rolling:
- "Roll 1d20+5 for an attack roll"
- "Roll 4d6 drop lowest for ability scores"
- "Roll 2d10+3 for damage"
Game Data:
- "Show me all the NPCs in this scene"
- "Find magic weapons in the party's inventory"
- "What's the current combat initiative order?"
- "Search for healing potions"
Content Generation:
- "Generate a random NPC merchant"
- "Create loot for a CR 5 encounter"
- "Generate a tavern with NPCs and plot hooks"
Advanced Features
Rule Lookups:
- "Look up the grappling rules"
- "How does the Fireball spell work?"
- "What are the conditions for being frightened?"
Tactical Advice:
- "Suggest tactics for fighting a dragon"
- "What should our wizard do this turn?"
- "Analyze this combat encounter"
World Building:
- "Create a mysterious forest location"
- "Generate a side quest involving missing merchants"
- "Design a magic item appropriate for level 8 characters"
Available Tools
Data Access
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 information
Game Mechanics
roll_dice
- Roll dice with any formulaupdate_actor_hp
- Modify character healthget_combat_status
- Combat state and initiativelookup_rule
- Game rules and spell descriptions
Content Generation
generate_npc
- Create random NPCsgenerate_loot
- Create treasure appropriate for levelroll_table
- Random encounters, events, weathersuggest_tactics
- Combat advice and strategy
Diagnostics & System Health
get_system_health
- Server performance and health metricsget_recent_logs
- Retrieve filtered FoundryVTT logssearch_logs
- Search logs with regex patternsdiagnose_errors
- Analyze errors with troubleshooting suggestions
Available Resources
The 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 database
Configuration
Server Settings
Edit .env
to customize:
Security
- Use API keys instead of passwords when possible
- Limit FoundryVTT user permissions to minimum required
- Run server on internal network only
- Monitor logs for suspicious activity
Diagnostics & Troubleshooting
Built-in Diagnostics
The server includes comprehensive diagnostic tools to help troubleshoot connection and performance issues:
Connection Testing:
Diagnostic Tools (via AI assistant):
- System Health: "Get the FoundryVTT system health status"
- Error Analysis: "Diagnose recent errors and provide recommendations"
- Log Search: "Search logs for 'connection' patterns in the last hour"
- Recent Issues: "Show me recent error logs"
Advanced Diagnostics
When using the Local REST API module, you get access to advanced diagnostic features:
- 🔍 Real-time Log Analysis - Monitor FoundryVTT console output and notifications
- 📊 System Health Metrics - Server performance, memory usage, and client connections
- 🎯 Error Pattern Recognition - Automatic detection of common issues
- 💡 Smart Suggestions - Context-aware troubleshooting recommendations
- 📈 Performance Monitoring - Track server uptime and response times
Connection Issues
Common Problems
"Failed to connect to FoundryVTT"
- Verify FOUNDRY_URL is correct
- Check if FoundryVTT is running
- Ensure API access is enabled
"Authentication failed"
- Verify API key or username/password
- Check user permissions in FoundryVTT
- Ensure user is not banned/restricted
"Tool not found" errors
- Update to latest server version
- Check tool name spelling
- Review available tools in logs
Development
Project Structure
Adding New Tools
- Define tool schema in
src/tools/index.ts
- Add handler method in
src/index.ts
- Implement FoundryVTT API calls in
src/foundry/client.ts
- Add TypeScript types in
src/foundry/types.ts
- Test with your AI assistant
Testing
Building
API Reference
Environment Variables
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
Tool Schemas
roll_dice
search_actors
generate_npc
Integration Examples
Claude Desktop Configuration
Add to your Claude Desktop MCP settings:
Custom MCP Client
Roadmap
Version 0.2.0
- Combat management tools (start/end combat, advance initiative)
- Token manipulation (move, update status effects)
- Scene navigation and switching
- Playlist controls and ambient audio
Version 0.3.0
- Character sheet editing (level up, add equipment)
- Journal entry creation and editing
- Macro execution and management
- Advanced content generation (dungeons, NPCs with full stats)
Version 1.0.0
- Multi-world support
- User permission management
- Webhook support for external triggers
- Performance optimization and caching
- Full test coverage
- Docker deployment
Documentation
Complete API documentation is available in the docs/
directory, auto-generated from TypeScript source code and JSDoc comments.
📖 Viewing Documentation
Local development:
Online: Browse the docs/
folder in this repository or visit the GitHub Pages site (if enabled).
📚 What's Documented
- FoundryClient API - Complete client documentation with examples
- TypeScript Interfaces - All data structures and type definitions
- Configuration - Environment variables and setup options
- Utilities - Helper functions and logging
- Usage Examples - Code samples for common operations
The documentation is automatically updated via GitHub Actions when source code changes.
Contributing
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature
- Make your changes and add tests
- Commit:
git commit -m 'Add amazing feature'
- Push:
git push origin feature/amazing-feature
- Open a Pull Request
Code Style
- Use TypeScript strict mode
- Follow existing naming conventions
- Add JSDoc comments for public APIs
- Write tests for new functionality
- Use meaningful commit messages
License
MIT License - see LICENSE file for details.
Troubleshooting
🔍 Quick Diagnostics
🏥 Health Check
Use the get_health_status
MCP tool for comprehensive diagnostics, or check server logs during startup for detailed status information.
📚 Common Issues
- Connection refused: Ensure FoundryVTT is running on the configured port
- Authentication failed: Verify API key or username/password in
.env
- Empty search results: Install and enable the "Foundry Local REST API" module
- Limited functionality: REST API module required for full features
📖 Detailed troubleshooting guide: TROUBLESHOOTING.md
Support
- Issues: GitHub Issues for bugs and feature requests
- Discord: FoundryVTT Discord #api-development
- Documentation: FoundryVTT API Docs
- Troubleshooting: TROUBLESHOOTING.md
Acknowledgments
- FoundryVTT team for the excellent VTT platform
- Anthropic for the Model Context Protocol
- The tabletop gaming community for inspiration and feedback
Happy Gaming! 🎲
This server cannot be installed
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
A Model Context Protocol server that integrates with FoundryVTT, allowing AI assistants to interact with tabletop gaming sessions through natural language to query actors, roll dice, generate content, and manage game worlds.
Related MCP Servers
- AsecurityAlicenseAqualityA Model Context Protocol server that allows AI assistants to interact with the VRChat API, enabling retrieval of user information, friends lists, and other VRChat data through a standardized interface.Last updated -713233TypeScriptMIT License
- -securityAlicense-qualityA Model Context Protocol server that enables AI assistants to interact with the Godot game engine, allowing them to launch the editor, run projects, capture debug output, and control project execution.Last updated -62JavaScriptMIT License
- AsecurityFlicenseAqualityA Model Context Protocol server that enables AI agents to generate, fetch, and manage UI components through natural language interactions.Last updated -3194TypeScript
- -securityAlicense-qualityA Model Context Protocol server that enables interaction with Foundry tools through natural language, allowing users to create projects, build contracts, run tests, and manage Ethereum development environments.Last updated -1PythonMIT License