foundryvtt-mcp

laurigates/foundryvtt-mcp

3.3

If you are the rightful owner of foundryvtt-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The FoundryVTT MCP Server is a Model Context Protocol server that integrates with FoundryVTT, enabling AI assistants to interact with tabletop gaming sessions.

The FoundryVTT MCP Server is designed to enhance tabletop gaming experiences by integrating AI capabilities with FoundryVTT. This server allows AI assistants to perform various tasks such as querying game data, rolling dice, generating content, and managing game worlds through natural language. It supports real-time integration with live updates, combat management, and user awareness features. The server is built to be secure and efficient, offering local-only authentication methods to ensure privacy and control over game data. With AI-powered features, it provides tactical suggestions, story assistance, and world-building tools, making it a versatile addition to any gaming session.

Features

  • Dice Rolling: Roll dice using standard RPG notation.
  • Data Querying: Search actors, items, scenes, and journal entries.
  • Game State Access: Access current scene, combat status, and world information.
  • Content Generation: Generate NPCs, loot, and random encounters.
  • Rule Lookup: Query game rules and mechanical information.

Usages

usage with Claude Desktop

{
  "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"
      }
    }
  }
}

usage with Custom MCP Client

typescript
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",
    },
  },
});

Tools

  1. roll_dice

    Roll dice with any formula.

  2. search_actors

    Find characters, NPCs, monsters.

  3. generate_npc

    Create random NPCs.