FoundryMCP

A lightweight MCP (Model Context Protocol) server for FoundryVTT that communicates directly via WebSockets.

Why This Server?

Unlike other FoundryVTT MCP servers that require:

• Installing a custom module on your Foundry server
• Running a headless browser

This server natively authenticates with FoundryVTT and exchanges WebSocket messages directly using the same protocol as the official Foundry client. This makes it:

• Lightweight - No browser overhead, just direct WebSocket communication
• Zero server-side setup - No modules to install on your Foundry instance
• Secure - Uses the same authentication flow as the official client

Compatibility

Works with FoundryVTT v13 and v14. The server detects the Foundry generation automatically (via GET /api/status) and uses the correct session-binding method for that version — v14 changed how the WebSocket session is authenticated, and both are handled transparently with no configuration needed.

Security Recommendation

Create a dedicated FoundryVTT user for each game world you want the MCP server to access. Grant that user only the permissions you want the MCP server to have. This provides:

• Fine-grained access control
• Clear audit trail of MCP actions
• Easy revocation if needed
• Isolation between different games/worlds

Installation

npm install
npm run build

Skills

The ./skills directory contains LLM skills for this project. Currently the only skill there is MAIN.skill, and all users should install it because it includes the FoundryVTT-specific guidance and workflows. We welcome PRs that add skills for specific game systems, FoundryVTT modules, or other targeted use cases.

Configuration

Credentials File

Create a file at config/foundry_credentials.json:

[
  {
    "_id": "my-campaign",
    "hostname": "your-foundry-server.com",
    "userid": "your-user-id",
    "password": "your-password"
  },
  {
    "_id": "test-world",
    "hostname": "test.foundry-server.com",
    "username": "Gamemaster",
    "password": "test-password"
  }
]

Fields:

• _id - A user-defined identifier for this credential entry (used to switch between instances)
• hostname - The domain/IP of your FoundryVTT server
• userid - Your Foundry user document ID (find by inspecting Users in Foundry admin panel)
• username - Your Foundry user name
  • Give userid, username, or both. If only one is given, the other is looked up from the world’s user list before logging in. If both are given, they are used as-is. Name lookup is exact first, then case-insensitive.
• password - Your Foundry user password
• allow_insecure_tls - Optional. Set to true only for a trusted Foundry server with a self-signed certificate. Defaults to false.

Disabling TLS verification makes the connection vulnerable to interception. Prefer a trusted certificate when one is available.