{"id":38704787,"url":"https://github.com/laurigates/foundryvtt-mcp","last_synced_at":"2026-03-07T20:11:55.435Z","repository":{"id":298855745,"uuid":"1001334381","full_name":"laurigates/foundryvtt-mcp","owner":"laurigates","description":"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.","archived":false,"fork":false,"pushed_at":"2025-08-21T11:55:14.000Z","size":514,"stargazers_count":5,"open_issues_count":4,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-08-21T13:36:39.414Z","etag":null,"topics":["foundryvtt-module","mcp-server"],"latest_commit_sha":null,"homepage":"https://laurigates.github.io/foundryvtt-mcp/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/laurigates.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-13T07:50:26.000Z","updated_at":"2025-08-21T11:55:03.000Z","dependencies_parsed_at":"2025-06-13T09:23:28.452Z","dependency_job_id":"18a75a47-ac74-4e36-8be3-dc4f8dcf4307","html_url":"https://github.com/laurigates/foundryvtt-mcp","commit_stats":null,"previous_names":["laurigates/foundryvtt-mcp"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/laurigates/foundryvtt-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Ffoundryvtt-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Ffoundryvtt-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Ffoundryvtt-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Ffoundryvtt-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/laurigates","download_url":"https://codeload.github.com/laurigates/foundryvtt-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/laurigates%2Ffoundryvtt-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28506593,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T10:25:30.148Z","status":"ssl_error","status_checked_at":"2026-01-17T10:25:29.718Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["foundryvtt-module","mcp-server"],"created_at":"2026-01-17T10:54:40.298Z","updated_at":"2026-01-17T10:54:40.861Z","avatar_url":"https://github.com/laurigates.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# FoundryVTT MCP Server\n\nA 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.\n\n## Features\n\n### Core Functionality\n\n- 🎲 **Dice Rolling** - Roll dice with standard RPG notation\n- 🔍 **Data Querying** - Search actors, items, scenes, and journal entries\n- 📊 **Game State** - Access current scene, combat status, and world information\n- 🎭 **Content Generation** - Generate NPCs, loot, and random encounters\n- 📝 **Rule Lookup** - Query game rules and mechanical information\n\n### Real-time Integration\n\n- 🔄 **Live Updates** - WebSocket connection for real-time game state\n- ⚔️ **Combat Management** - Track initiative and combat state\n- 👥 **User Awareness** - See who's online and their status\n\n### AI-Powered Features\n\n- 🧠 **Tactical Suggestions** - Get combat advice and strategy tips\n- 🎪 **Story Assistance** - Generate plot hooks and narrative elements\n- 🎨 **World Building** - Create locations, NPCs, and quests on demand\n\n## Installation\n\n### Prerequisites\n\n- Node.js 18+\n- FoundryVTT server running and accessible\n- MCP-compatible AI client (Claude Desktop, etc.)\n\n### Quick Setup (Recommended)\n\n**🧙‍♂️ Interactive Setup Wizard:**\n```bash\ngit clone \u003crepository-url\u003e\ncd foundry-mcp-server\nnpm install\nnpm run setup-wizard\n```\n\nThe setup wizard will:\n- Automatically detect your FoundryVTT server\n- Test connectivity and authentication\n- Generate your `.env` configuration file\n- Validate the complete setup\n\n### Manual Setup\n\n1. **Clone and install:**\n\n```bash\ngit clone \u003crepository-url\u003e\ncd foundry-mcp-server\nnpm install\n```\n\n2. **Configure environment:**\n\n```bash\ncp .env.example .env\n# Edit .env with your FoundryVTT details\n```\n\n3. **Required environment variables:**\n\n```env\nFOUNDRY_URL=http://localhost:30000\nFOUNDRY_API_KEY=your_api_key_here\n# OR use username/password:\nFOUNDRY_USERNAME=your_username\nFOUNDRY_PASSWORD=your_password\n```\n\n4. **Test and start:**\n\n```bash\nnpm run test-connection  # Verify setup\nnpm run build\nnpm start\n```\n\n### Development Mode\n\n```bash\nnpm run dev\n```\n\n## FoundryVTT Configuration\n\nThe MCP server supports two secure, local-only authentication methods:\n\n### Option 1: Local REST API Module (🔒 Recommended)\n\n**Benefits:**\n\n- ✅ **100% Local** - No external dependencies or third-party services\n- ✅ **Maximum Privacy** - Your game data never leaves your network\n- ✅ **Full Control** - You own and manage all authentication\n- ✅ **Better Performance** - Direct local API access\n- ✅ **Complete API Access** - Full access to all FoundryVTT features\n\n**Setup:**\n\n1. Install the **Foundry Local REST API** module:\n   - In FoundryVTT: **Setup** → **Add-on Modules** → **Install Module**\n   - Paste: `https://github.com/laurigates/foundryvtt-mcp/releases/latest/download/module.json`\n2. Enable the module in your world\n3. Go to **Settings** → **Configure Settings** → **Module Settings**\n4. Find **\"Foundry Local REST API\"** and check **\"Enable REST API\"**\n5. Copy the generated **API Key**\n6. Add to your `.env` file:\n   ```env\n   FOUNDRY_URL=http://localhost:30000\n   FOUNDRY_API_KEY=your_local_api_key_here\n   ```\n\n### Option 2: Username/Password (Fallback)\n\n**Use when:** Local REST API module is not available or for simple setups.\n\n**Limitations:** Some advanced features may not work properly.\n\n1. Ensure your FoundryVTT user has appropriate permissions\n2. Add credentials to `.env` file:\n   ```env\n   FOUNDRY_URL=http://localhost:30000\n   FOUNDRY_USERNAME=your_username\n   FOUNDRY_PASSWORD=your_password\n   ```\n\n### Comparison Table\n\n| Feature         | **Local REST API Module**  | **Username/Password**    |\n| --------------- | -------------------------- | ------------------------ |\n| **Privacy**     | ✅ 100% Local              | ✅ 100% Local            |\n| **Security**    | ✅ API Key auth            | ⚠️ Password auth         |\n| **Performance** | ✅ Direct API access       | ⚠️ WebSocket only        |\n| **Features**    | ✅ Complete API access     | ❌ Limited functionality |\n| **Setup**       | ⚠️ Module install required | ✅ Simple credentials    |\n| **Reliability** | ✅ Stable API              | ⚠️ Connection dependent  |\n\n### Required Permissions (All Methods)\n\nYour FoundryVTT user needs these permissions:\n\n- View actors, items, scenes, and journals\n- Create and modify journal entries (for content generation)\n- Access compendium data\n- Use dice rolling API\n\n## Usage\n\n### Basic Queries\n\nAsk your AI assistant things like:\n\n**Dice Rolling:**\n\n- \"Roll 1d20+5 for an attack roll\"\n- \"Roll 4d6 drop lowest for ability scores\"\n- \"Roll 2d10+3 for damage\"\n\n**Game Data:**\n\n- \"Show me all the NPCs in this scene\"\n- \"Find magic weapons in the party's inventory\"\n- \"What's the current combat initiative order?\"\n- \"Search for healing potions\"\n\n**Content Generation:**\n\n- \"Generate a random NPC merchant\"\n- \"Create loot for a CR 5 encounter\"\n- \"Generate a tavern with NPCs and plot hooks\"\n\n### Advanced Features\n\n**Rule Lookups:**\n\n- \"Look up the grappling rules\"\n- \"How does the Fireball spell work?\"\n- \"What are the conditions for being frightened?\"\n\n**Tactical Advice:**\n\n- \"Suggest tactics for fighting a dragon\"\n- \"What should our wizard do this turn?\"\n- \"Analyze this combat encounter\"\n\n**World Building:**\n\n- \"Create a mysterious forest location\"\n- \"Generate a side quest involving missing merchants\"\n- \"Design a magic item appropriate for level 8 characters\"\n\n## Available Tools\n\n### Data Access\n\n- `search_actors` - Find characters, NPCs, monsters\n- `search_items` - Find equipment, spells, consumables\n- `search_journals` - Search notes and handouts\n- `get_scene_info` - Current scene details\n- `get_actor_details` - Detailed character information\n\n### Game Mechanics\n\n- `roll_dice` - Roll dice with any formula\n- `update_actor_hp` - Modify character health\n- `get_combat_status` - Combat state and initiative\n- `lookup_rule` - Game rules and spell descriptions\n\n### Content Generation\n\n- `generate_npc` - Create random NPCs\n- `generate_loot` - Create treasure appropriate for level\n- `roll_table` - Random encounters, events, weather\n- `suggest_tactics` - Combat advice and strategy\n\n### Diagnostics \u0026 System Health\n\n- `get_system_health` - Server performance and health metrics\n- `get_recent_logs` - Retrieve filtered FoundryVTT logs\n- `search_logs` - Search logs with regex patterns\n- `diagnose_errors` - Analyze errors with troubleshooting suggestions\n\n## Available Resources\n\nThe server exposes these FoundryVTT resources:\n\n- `foundry://world/info` - World and campaign information\n- `foundry://world/actors` - All actors in the world\n- `foundry://scene/current` - Current active scene\n- `foundry://combat/current` - Active combat state\n- `foundry://compendium/spells` - Spell database\n- `foundry://compendium/monsters` - Monster database\n\n## Configuration\n\n### Server Settings\n\nEdit `.env` to customize:\n\n```env\n# Logging\nLOG_LEVEL=info  # debug, info, warn, error\n\n# Performance\nFOUNDRY_TIMEOUT=10000      # Request timeout (ms)\nFOUNDRY_RETRY_ATTEMPTS=3   # Retry failed requests\nCACHE_TTL_SECONDS=300      # Cache data for 5 minutes\n```\n\n### Security\n\n- Use API keys instead of passwords when possible\n- Limit FoundryVTT user permissions to minimum required\n- Run server on internal network only\n- Monitor logs for suspicious activity\n\n## Diagnostics \u0026 Troubleshooting\n\n### Built-in Diagnostics\n\nThe server includes comprehensive diagnostic tools to help troubleshoot connection and performance issues:\n\n**Connection Testing:**\n```bash\n# Test complete MCP connection and functionality\nnpm run test-connection\n\n# Clean build and test setup\nnpm run setup\n```\n\n**Diagnostic Tools (via AI assistant):**\n- **System Health:** \"Get the FoundryVTT system health status\"\n- **Error Analysis:** \"Diagnose recent errors and provide recommendations\"\n- **Log Search:** \"Search logs for 'connection' patterns in the last hour\"\n- **Recent Issues:** \"Show me recent error logs\"\n\n### Advanced Diagnostics\n\nWhen using the **Local REST API module**, you get access to advanced diagnostic features:\n\n- 🔍 **Real-time Log Analysis** - Monitor FoundryVTT console output and notifications\n- 📊 **System Health Metrics** - Server performance, memory usage, and client connections\n- 🎯 **Error Pattern Recognition** - Automatic detection of common issues\n- 💡 **Smart Suggestions** - Context-aware troubleshooting recommendations\n- 📈 **Performance Monitoring** - Track server uptime and response times\n\n### Connection Issues\n\n```bash\n# Test FoundryVTT connection\ncurl http://localhost:30000/api/status\n\n# Check server logs\nnpm run dev  # Shows detailed logging\n```\n\n### Common Problems\n\n**\"Failed to connect to FoundryVTT\"**\n\n- Verify FOUNDRY_URL is correct\n- Check if FoundryVTT is running\n- Ensure API access is enabled\n\n**\"Authentication failed\"**\n\n- Verify API key or username/password\n- Check user permissions in FoundryVTT\n- Ensure user is not banned/restricted\n\n**\"Tool not found\" errors**\n\n- Update to latest server version\n- Check tool name spelling\n- Review available tools in logs\n\n## Development\n\n### Project Structure\n\n```\nsrc/\n├── config/           # Configuration management\n├── foundry/          # FoundryVTT client and types\n├── tools/            # MCP tool definitions\n├── resources/        # MCP resource definitions\n├── utils/            # Utilities and logging\n└── index.ts          # Main server entry point\n```\n\n### Adding New Tools\n\n1. Define tool schema in `src/tools/index.ts`\n2. Add handler method in `src/index.ts`\n3. Implement FoundryVTT API calls in `src/foundry/client.ts`\n4. Add TypeScript types in `src/foundry/types.ts`\n5. Test with your AI assistant\n\n### Testing\n\n```bash\n# Run tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Lint code\nnpm run lint\n```\n\n### Building\n\n```bash\n# Development build\nnpm run build\n\n# Clean build\nnpm run clean \u0026\u0026 npm run build\n```\n\n## API Reference\n\n### Environment Variables\n\n| Variable                 | Required | Description                | Default       |\n| ------------------------ | -------- | -------------------------- | ------------- |\n| `FOUNDRY_URL`            | ✅       | FoundryVTT server URL      | -             |\n| `FOUNDRY_API_KEY`        | ⭐       | API key for authentication | -             |\n| `FOUNDRY_USERNAME`       | ⭐       | Username (if no API key)   | -             |\n| `FOUNDRY_PASSWORD`       | ⭐       | Password (if no API key)   | -             |\n| `LOG_LEVEL`              | ❌       | Logging verbosity          | `info`        |\n| `NODE_ENV`               | ❌       | Environment mode           | `development` |\n| `FOUNDRY_TIMEOUT`        | ❌       | Request timeout (ms)       | `10000`       |\n| `FOUNDRY_RETRY_ATTEMPTS` | ❌       | Retry failed requests      | `3`           |\n| `CACHE_TTL_SECONDS`      | ❌       | Cache duration             | `300`         |\n\n⭐ Either API key OR username/password required\n\n### Tool Schemas\n\n#### roll_dice\n\n```json\n{\n  \"formula\": \"1d20+5\",\n  \"reason\": \"Attack roll against goblin\"\n}\n```\n\n#### search_actors\n\n```json\n{\n  \"query\": \"goblin\",\n  \"type\": \"npc\",\n  \"limit\": 10\n}\n```\n\n#### generate_npc\n\n```json\n{\n  \"race\": \"human\",\n  \"level\": 5,\n  \"role\": \"merchant\",\n  \"alignment\": \"neutral good\"\n}\n```\n\n## Integration Examples\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"foundry\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/foundry-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"FOUNDRY_URL\": \"http://localhost:30000\",\n        \"FOUNDRY_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Custom MCP Client\n\n```typescript\nimport { Client } from \"@modelcontextprotocol/sdk/client/index.js\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\nconst transport = new StdioClientTransport({\n  command: \"node\",\n  args: [\"./dist/index.js\"],\n});\n\nconst client = new Client(\n  {\n    name: \"foundry-client\",\n    version: \"1.0.0\",\n  },\n  {\n    capabilities: {},\n  },\n);\n\nawait client.connect(transport);\n\n// Roll dice\nconst result = await client.request({\n  method: \"tools/call\",\n  params: {\n    name: \"roll_dice\",\n    arguments: {\n      formula: \"1d20+5\",\n      reason: \"Initiative roll\",\n    },\n  },\n});\n```\n\n## Roadmap\n\n### Version 0.2.0\n\n- [ ] Combat management tools (start/end combat, advance initiative)\n- [ ] Token manipulation (move, update status effects)\n- [ ] Scene navigation and switching\n- [ ] Playlist controls and ambient audio\n\n### Version 0.3.0\n\n- [ ] Character sheet editing (level up, add equipment)\n- [ ] Journal entry creation and editing\n- [ ] Macro execution and management\n- [ ] Advanced content generation (dungeons, NPCs with full stats)\n\n### Version 1.0.0\n\n- [ ] Multi-world support\n- [ ] User permission management\n- [ ] Webhook support for external triggers\n- [ ] Performance optimization and caching\n- [ ] Full test coverage\n- [ ] Docker deployment\n\n## Documentation\n\nComplete API documentation is available in the `docs/` directory, auto-generated from TypeScript source code and JSDoc comments.\n\n### 📖 Viewing Documentation\n\n**Local development:**\n\n```bash\nnpm run docs        # Generate documentation\nnpm run docs:serve  # Generate and serve locally\n```\n\n**Online:** Browse the `docs/` folder in this repository or visit the GitHub Pages site (if enabled).\n\n### 📚 What's Documented\n\n- **FoundryClient API** - Complete client documentation with examples\n- **TypeScript Interfaces** - All data structures and type definitions\n- **Configuration** - Environment variables and setup options\n- **Utilities** - Helper functions and logging\n- **Usage Examples** - Code samples for common operations\n\nThe documentation is automatically updated via GitHub Actions when source code changes.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature/amazing-feature`\n3. Make your changes and add tests\n4. Commit: `git commit -m 'Add amazing feature'`\n5. Push: `git push origin feature/amazing-feature`\n6. Open a Pull Request\n\n### Code Style\n\n- Use TypeScript strict mode\n- Follow existing naming conventions\n- Add JSDoc comments for public APIs\n- Write tests for new functionality\n- Use meaningful commit messages\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Troubleshooting\n\n### 🔍 Quick Diagnostics\n```bash\nnpm run test-connection      # Test FoundryVTT connectivity\nnpm run setup-wizard        # Re-run interactive setup\n```\n\n### 🏥 Health Check\nUse the `get_health_status` MCP tool for comprehensive diagnostics, or check server logs during startup for detailed status information.\n\n### 📚 Common Issues\n- **Connection refused**: Ensure FoundryVTT is running on the configured port\n- **Authentication failed**: Verify API key or username/password in `.env`\n- **Empty search results**: Install and enable the \"Foundry Local REST API\" module\n- **Limited functionality**: REST API module required for full features\n\n**📖 Detailed troubleshooting guide**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\n\n## Support\n\n- **Issues**: GitHub Issues for bugs and feature requests\n- **Discord**: [FoundryVTT Discord](https://discord.gg/foundryvtt) #api-development\n- **Documentation**: [FoundryVTT API Docs](https://foundryvtt.com/api/)\n- **Troubleshooting**: [TROUBLESHOOTING.md](TROUBLESHOOTING.md)\n\n## Acknowledgments\n\n- FoundryVTT team for the excellent VTT platform\n- Anthropic for the Model Context Protocol\n- The tabletop gaming community for inspiration and feedback\n\n---\n\n**Happy Gaming! 🎲**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurigates%2Ffoundryvtt-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flaurigates%2Ffoundryvtt-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flaurigates%2Ffoundryvtt-mcp/lists"}