Skip to content
Back to search

foundry-vtt-mcp

An MCP (Model Context Protocol) server that bridges Foundry VTT data with Claude Desktop, enabling users to chat with their game world data using their own Claude subscription.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/adambdooley--foundry-vtt-mcp/badge.svg)](/listings/adambdooley--foundry-vtt-mcp)

HTML

<a href="/listings/adambdooley--foundry-vtt-mcp"><img src="/api/listings/adambdooley--foundry-vtt-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- **Foundry VTT v13 or v14** - **Claude Desktop** with MCP support - **Windows** (for automated installer) or **Node.js 18+** for manual installation

Option 1: Windows Installer

[Video guide for Windows Installer](https://youtu.be/Se04A21wrbE)

1. Download the latest `FoundryMCPServer-Setup-vx.x.x.exe` from [Releases](https://github.com/adambdooley/foundry-vtt-mcp/releases) 2. Run the installer - it will: - Install the MCP server with bundled Node.js runtime - Configure the Claude Desktop MCP server settings - Optionally install the Foundry module and ComfyUI Map Generation to your VTT installation - Choose Cuda version for your GPU type during install 3. Restart Claude Desktop 4. Enable "Foundry MCP Bridge" in your Foundry Module Management

Option 2: Mac Installer

1. Download the latest `FoundryMCPServer-vx.x.x.dmg` from [Releases](https://github.com/adambdooley/foundry-vtt-mcp/releases) 2. Run the package installer inside the dmg - it will: - Open DMG and double-click the PKG installer - Configure the Claude Desktop MCP server settings - Optionally install the Foundry module and ComfyUI Map Generation to your Foundry VTT installation 3. Restart Claude Desktop 4. Enable "Foundry MCP Bridge" in your Foundry Module Management

Option 3: Manual Installation

Install the Foundry Module

1. Open Foundry VTT (v13 or v14) 2. Select install module in the Foundry Add-ons menu 3. At the bottom of the window, add the Manifest URL as: https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json and click install 4. Enable "Foundry MCP Bridge" in Module Management - **Do not change the module ID or folder name.** The MCP backend and the Claude integration both expect the module to live in a directory called `foundry-mcp-bridge`. Renaming the ID in `module.json` breaks socket routing and stops Claude from seeing the backend.

Install the MCP Server

# Clone repository
git clone https://github.com/adambdooley/foundry-vtt-mcp.git
cd foundry-vtt-mcp

# Install dependencies and build
npm install
npm run build

Configure Claude Desktop

Add this to your Claude Desktop configuration (claude_desktop_config.json) file:

{
  "mcpServers": {
    "foundry-mcp": {
      "command": "node",
      "args": ["path/to/foundry-vtt-mcp/packages/mcp-server/dist/index.js"],
      "env": {
        "FOUNDRY_HOST": "localhost",
        "FOUNDRY_PORT": "31415"
      }
    }
  }
}

Starting Claude Desktop will start the MCP Server.

> **Windows Store / MSIX installs:** If you installed Claude Desktop from the Microsoft Store, it reads its config from a virtualised path, not `%APPDATA%\Claude\`. Edit `claude_desktop_config.json` here instead: > `%LOCALAPPDATA%\Packages\<...Claude...>\LocalCache\Roaming\Claude\claude_desktop_config.json` > The automated Windows installer (v0.8.1+) writes to both locations for you. Note that a major Claude Desktop update can reset this container — if your tools disappear after an update, re-run the installer or re-add the `mcpServers` block at that path.

Getting Started

1. Start Foundry VTT and load your world 2. Open Claude Desktop 3. Chat with Claude about your currently loaded Foundry World

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 260 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Foundry VTT MCP Bridge
  2. Connect Foundry VTT to Claude Desktop for AI-powered campaign management through the Model Context Protocol (MCP). It currently supports Dungeons and Dragons Fifth Edition, Pathfinder Second Edition, Das Schwarze Augen Fifth Edition, Cosmere RPG System, Warhammer Fantasy Roleplay 4th Edition, & Mongoose Traveller 2nd Edition. The majority of MCP tools are system agnostic or have features that are aware of the system it is working with, excluding some DSA 5 specific tools.
  3. ## Overview
  4. The Foundry MCP Bridge enables natural AI conversations with your Foundry VTT game data:
  5. - **Quest Creation**: [Create quests from prompts that incorporate what exists in your world and journals](https://www.youtube.com/watch?v=NqyB_z2AKME)
  6. - **Character Management**: Query character stats, abilities, and information
  7. - **Compendium Search**: Find items, spells, and creatures using natural language
  8. - **Content Creation**: Generate actors, NPCs, and quest journals from simple prompts
  9. - **Scene Information**: Access current scene data and world details
  10. - **Dice Coordination**: Interactive roll requests with player targeting
  11. - **Campaign Management**: Multi-part quest and campaign tracking
  12. - **Map Generation**: Create maps from prompts and automatically upload them into scenes in Foundry VTT using the optional ComfyUI component
  13. ## Installation
  14. ### Prerequisites
  15. - **Foundry VTT v13 or v14**
  16. - **Claude Desktop** with MCP support
  17. - **Windows** (for automated installer) or **Node.js 18+** for manual installation
  18. ### Option 1: Windows Installer
  19. [Video guide for Windows Installer](https://youtu.be/Se04A21wrbE)
  20. 1. Download the latest `FoundryMCPServer-Setup-vx.x.x.exe` from [Releases](https://github.com/adambdooley/foundry-vtt-mcp/releases)
  21. 2. Run the installer - it will:
  22. - Install the MCP server with bundled Node.js runtime
  23. - Configure the Claude Desktop MCP server settings
  24. - Optionally install the Foundry module and ComfyUI Map Generation to your VTT installation
  25. - Choose Cuda version for your GPU type during install
  26. 3. Restart Claude Desktop
  27. 4. Enable "Foundry MCP Bridge" in your Foundry Module Management
  28. ### Option 2: Mac Installer
  29. 1. Download the latest `FoundryMCPServer-vx.x.x.dmg` from [Releases](https://github.com/adambdooley/foundry-vtt-mcp/releases)
  30. 2. Run the package installer inside the dmg - it will:
  31. - Open DMG and double-click the PKG installer
  32. - Configure the Claude Desktop MCP server settings
  33. - Optionally install the Foundry module and ComfyUI Map Generation to your Foundry VTT installation
  34. 3. Restart Claude Desktop
  35. 4. Enable "Foundry MCP Bridge" in your Foundry Module Management
  36. ### Option 3: Manual Installation
  37. #### Install the Foundry Module
  38. 1. Open Foundry VTT (v13 or v14)
  39. 2. Select install module in the Foundry Add-ons menu
  40. 3. At the bottom of the window, add the Manifest URL as: https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json and click install
  41. 4. Enable "Foundry MCP Bridge" in Module Management
  42. - **Do not change the module ID or folder name.** The MCP backend and the Claude integration both expect the module to live in a directory called `foundry-mcp-bridge`. Renaming the ID in `module.json` breaks socket routing and stops Claude from seeing the backend.
  43. #### Install the MCP Server
  44. ```bash
  45. # Clone repository
  46. git clone https://github.com/adambdooley/foundry-vtt-mcp.git
  47. cd foundry-vtt-mcp
  48. # Install dependencies and build
  49. npm install
  50. npm run build
  51. ```
  52. #### Configure Claude Desktop
  53. Add a `foundry-mcp` entry to the `mcpServers` section of your Claude Desktop configuration file (`claude_desktop_config.json`):
  54. ```json
  55. {
  56. "mcpServers": {
  57. "foundry-mcp": {
  58. "command": "node",
  59. "args": ["path/to/foundry-vtt-mcp/packages/mcp-server/dist/index.js"]
  60. }
  61. }
  62. }
  63. ```
  64. If the file already has content, add the `foundry-mcp` entry inside the existing `mcpServers` object (create `mcpServers` if it isn't there) rather than pasting the whole block above. A second top-level `{ }` makes the file invalid JSON, and Claude Desktop will fail to load it with a "non-whitespace character" error.
  65. No environment variables are needed for a standard setup. `FOUNDRY_PORT` sets the port the MCP server listens on for the Foundry module, and defaults to `31415`. It is not Foundry's own port (such as `30000`), and the module always connects on `31415`, so leave it unset.
  66. Starting Claude Desktop will start the MCP Server.
  67. > **Windows Store / MSIX installs:** If you installed Claude Desktop from the Microsoft Store, it reads its config from a virtualised path, not `%APPDATA%\Claude\`. Edit `claude_desktop_config.json` here instead:
  68. > `%LOCALAPPDATA%\Packages\<...Claude...>\LocalCache\Roaming\Claude\claude_desktop_config.json`
  69. > The automated Windows installer (v0.8.1+) writes to both locations for you. Note that a major Claude Desktop update can reset this container — if your tools disappear after an update, re-run the installer or re-add the `mcpServers` block at that path.
  70. ### Getting Started
  71. 1. Start Foundry VTT and load your world
  72. 2. Open Claude Desktop
  73. 3. Chat with Claude about your currently loaded Foundry World
  74. ## Example Usage
  75. Once connected, ask Claude Desktop:
  76. - _"Show me my character Clark's stats"_
  77. - _"Find all CR 12 humanoid creatures for an encounter"_
  78. - _"Create a quest about investigating missing villagers"_
  79. - _"Roll a stealth check for Tulkas"_
  80. - _"What's in the current Foundry scene?"_
  81. - _"Create me a small map of a Riverside Cottage in Foundry"_
  82. ## Features
  83. - **50 MCP Tools** that allow Claude to interact with Foundry
  84. - **D&D 5e NPC Creation Suite**: Build complete NPCs from prompts — stat block, attacks, saves, auras, and spellcasting
  85. - **Mongoose Traveller 2e (mgt2e) Support**: Full actor lifecycle — create/update/delete travellers, NPCs, creatures, and spacecraft with skill shorthand normalisation; creature compendium index with characteristic DMs; weapon-trait enum reference
  86. - **WFRP4e Support**: Character reading plus editing — update characteristics, wounds, skills and careers, and add or remove items on existing actors
  87. - **Generic Actor CRUD**: `manage-actors` creates, updates, and deletes actors of any type on any system; also updates and deletes embedded items
  88. - **Character Management**: Access stats, abilities, inventory, and detailed entity information
  89. - **Token Manipulation**: Move, update, delete tokens and manage status conditions
  90. - **Enhanced Compendium Search**: Instant filtering by CR, type, abilities, and more
  91. - **Content Creation**: Generate actors, NPCs, and quest journals (with optional folder organisation)
  92. - **World Item Management**: Create, list, and update world-level Items; attach items directly to actors
  93. - **Campaign Management**: Multi-part quest tracking with progress dashboards
  94. - **Interactive Dice System**: Send different dice roll requests to players from Claude
  95. - **Actor Ownership**: Manage player permissions for characters and tokens
  96. - **GM-Only**: MCP Bridge only connects to Game Master users
  97. - **Map Generation**: A portable ComfyUI backend that generates battlemaps from prompts
  98. - **Remote Connections**: WebRTC connections initiated through browser (Tested with Google Chrome) to MCP server and ComfyUI
  99. - **Windows and Mac Installers** Automated installation of Foundry MCP Server for Claude Dekstop, Foundry MCP Bridge Foundry VTT Module, and ComfyUI backend with dependencies
  100. ## MCP Tools
  101. - **1** get-world-info
  102. - **2** list-scenes
  103. - **3** get-current-scene
  104. - **4** get-available-conditions
  105. - **5** list-compendium-packs
  106. - **6** list-characters
  107. - **7** get-character
  108. - **8** search-character-items
  109. - **9** get-character-entity
  110. - **10** get-token-details
  111. - **11** toggle-token-condition (add / remove)
  112. - **12** update-token
  113. - **13** delete-tokens
  114. - **14** search-compendium
  115. - **15** get-compendium-item
  116. - **16** get-compendium-entry-full
  117. - **17** list-creatures-by-criteria
  118. - **18** list-journals
  119. - **19** create-quest-journal
  120. - **20** update-quest-journal
  121. - **21** search-journals
  122. - **22** replace-journal-page
  123. - **23** link-quest-to-npc
  124. - **24** list-actor-ownership
  125. - **25** assign-actor-ownership
  126. - **26** remove-actor-ownership
  127. - **27** move-token
  128. - **28** use-item
  129. - **29** request-player-rolls
  130. - **30** generate-map
  131. - **31** check-map-status
  132. - **32** cancel-map-job
  133. - **33** switch-scene
  134. - **34** update-scene-music
  135. - **35** manage-playlists (create / update / delete / describe — any system)
  136. - **36** control-playlist (play / stop / cycle-mode / play-sound / stop-sound)
  137. - **37** create-chat-message (speech bubble, chat-log line or whisper as an actor or token)
  138. - **38** create-actor-from-compendium
  139. - **39** list-dsa5-archetypes (DSA5 Only)
  140. - **40** create-dsa5-character-from-archetype (DSA5 Only)
  141. - **41** import-dsa5-actor-from-json (DSA5 Only)
  142. - **42** create-campaign-dashboard
  143. - **43** manage-world-items (create / list / get / update world items, add items to actor, describe system enum schema)
  144. - **44** manage-effects (create / update / delete ActiveEffects on actors or their items)
  145. - **45** dnd5e-create-npc (D&D 5e Only)
  146. - **46** dnd5e-add-feature (D&D 5e Only)
  147. - **47** dnd5e-add-features-from-compendium (D&D 5e Only)
  148. - **48** manage-actors (create / update / delete / place actors; update / delete embedded items — any system)
  149. - **49** wfrp4e-update-actor (WFRP4e Only)
  150. - **50** wfrp4e-add-items (WFRP4e Only)
  151. ## Settings
  152. <img width="964" height="803" alt="image" src="https://github.com/user-attachments/assets/bfd435d5-2df4-40a6-a79b-87e98121db3f" />
  153. - **Enhanced Creature Index** Configure Enhanced Index button leads to Enhanced Creature Index sub-menu (Details below)
  154. - **Map Generation Service Configuration** Configure Map Generation button leads to Map Generation Service sub-menu (Details below)
  155. - **Enable MCP Bridge** This should be checked by default and the status should show as connected. It can be used to turn off the MCP Bridge connection within the game without the need to disable the add-on itself.
  156. - **Connection Type** Can be set to Auto for automatic detection of connection type. Can also be set to force either WebRTC for Internet connections or Websocket for Local connections.
  157. - **Websocket Server Host** IP Address of Claude Desktop MCP Server location. Only used for local network websocket connections. Remote Servers use WebRT. Defaults to localhost.
  158. - **Allow Write Operations** This will prevent Claude from making any changes to world content and restrict it to reading only
  159. - **Max Actors Per Request** This is a failsafe to stop a massive amount of actors being created from one single request. It does not limit the amount of characters being created by multiple requests
  160. - **Show Connection Messages** This can turn off the banner messages for connections for Foundry MCP Bridge
  161. - **Auto-Reconnect on Disconnect** Will automatically attempt to reconnect if the connection is lost
  162. - **Connection Check Frequency** How often it will check connection status
  163. ### Enhanced Creature Index Sub-menu
  164. <img width="497" height="604" alt="image" src="https://github.com/user-attachments/assets/bf1a6fdb-9bd5-4256-b922-d28cf65b1e7d" />
  165. - **Rebuild Creature Index** This button will rebuild the creature index if there is an issue or it is out of sync with changes in your compendiums
  166. - **Enable Enhanced Creature Index** This should be left on as Claude builds additional metadata in the world files to give it better searches
  167. - **Auto-Rebuild Index on Pack Changes** Experimental feature that hasn't been fully tested yet
  168. ### Map Generation Service Sub-menu
  169. <img width="489" height="779" alt="image" src="https://github.com/user-attachments/assets/a43d3a3d-266f-41c9-b40a-236d14cfcba9" />
  170. - **Service Status** There are three buttons for Check Status, Start Service, and Stop Service. These buttons help monitor and control the connection from the Foundry MCP Bridge to the ComfyUI backend which is started by the Claude Desktop application.
  171. - **Auto-start Map Generation Service** Controls whether ComfyUI service connection is automatically connected at startup of the Foundry world.
  172. - **Generation Quality** Controls the quality of the maps generated by the SDXL checkpoints wiht ComfyUI. Low uses 8 steps of generation, Medium uses 20 steps of generation, and High uses 35 steps. The D&D Battlemaps SDXL Upscale v1.0 Checkpoint used in this image generation recommends using 35 steps but on low end GPUs or GPUs with out CUDA, this generation will take several minutes. These options can give you a trade off to have maps generated faster at the expense of quality.
  173. ## Architecture
  174. ```
  175. Claude Desktop ↔ MCP Protocol ↔ MCP Server ↔ WebSocket ↔ Foundry Module ↔ Foundry VTT
  176. ↓
  177. ComfyUI Service
  178. (AI Map Generation)
  179. ```
  180. - **Foundry Module**: Provides secure data access within Foundry VTT
  181. - **MCP Server**: External Node.js server handling Claude Desktop communication
  182. - **Map Generation Service**: A headless ComfyUI backend that is spawned by Claude Desktop
  183. - **No API Keys Required**: Uses your existing Claude Desktop subscription
  184. ## Security & Permissions
  185. - **GM-Only Access**: All functionality restricted to Game Master users
  186. - **Configurable Permissions**: Control what data Claude can access and modify
  187. - **Session-Based Authentication**: Uses Foundry's built-in authentication system
  188. ## System Requirements
  189. - **Foundry VTT**: Version 13
  190. - **Claude Desktop**: Latest version with MCP support
  191. - **Claude Pro/Max Plan**: Required to connect to MCP servers
  192. - **Operating System**: Windows 10/11 (installer), or other OSes/manual Windows install with Node.js 18+ (manual)
  193. - **GPU Requirements**: A GPU with at least 8GB of VRAM
  194. ## Schema Smoke Test
  195. The MCP schema smoke test verifies that tool schemas load correctly and do not enforce overly strict `additionalProperties` defaults.
  196. ```bash
  197. npm -w @foundry-mcp/server run build
  198. npm run test:mcp:schema
  199. ```
  200. ## Support & Development
  201. - **Issues**: Report bugs on [GitHub Issues](https://github.com/adambdooley/foundry-vtt-mcp/issues)
  202. - **YouTube Channel**: [Subscribe for updates and tutorials](https://www.youtube.com/channel/UCVrSC-FzuAk5AgvfboJj0WA)
  203. - **Documentation**: Built with TypeScript, comprehensive documentation included
  204. - **License**: MIT License (Additional Third Party licenses are included for bundled components for the installers)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.