FoundryVTT와 통합되는 Model Context Protocol (MCP) 서버는, AI 조수가 자연 언어를 통해 탁상 게임 세션과 상호 작용할 수 있도록 합니다.

특징

• Dice Rolling - 모든 공식과 표준 RPG 표기 -Data Querying - 검색 및 검사 배우, 항목, 장면, 저널 -Game State - 추적, 채팅 메시지, 사용자 존재 -Content Generation - NPC, loot 테이블, 규칙 조회 -World Search - 모든 게임에 대한 전체 텍스트 검색
• ** 연결** — 소켓. IO는 연결에 세계 국가를 완료
• MCP Resources - [T0]] URI를 직접 데이터 액세스
• Diagnostics - 옵션 서버 건강 모니터링 (REST API 모듈 필요)

빠른 시작

# 필수품

• Node.js 18+ (또는 분)
• FoundryVTT 서버는 활성 세계로 실행
• MCP 호환 AI 클라이언트 (클래드 데스크탑, 클로드 코드, VS 코드 등)

추천: 전용 API 사용자 만들기

MCP 서버의 별도 FoundryVTT 사용자 계정을 만들 것을 권장합니다. 이것은 더 나은 안전 및 감사를 제공합니다.

** FoundryVTT: **

1. Configuration → 사용자 관리
2. 명세.

FoundryVTT MCP Server

A Model Context Protocol (MCP) server that integrates with FoundryVTT, allowing AI assistants to interact with your tabletop gaming sessions through natural language.

Features

• Dice Rolling — standard RPG notation with any formula
• Data Querying — search and inspect actors, items, scenes, journals
• Game State — combat tracking, chat messages, user presence
• Content Generation — NPCs, loot tables, rule lookups
• World Search — full-text search across all game entities
• Live Connection — Socket.IO loads complete world state on connect
• MCP Resources — foundry:// URIs for direct data access
• Diagnostics — optional server health monitoring (requires REST API module)

Quick Start

Prerequisites

• Node.js 18+ (or Bun)
• FoundryVTT server running with an active world
• MCP-compatible AI client (Claude Desktop, Claude Code, VS Code, etc.)

Recommended: Create a Dedicated API User

It is recommended to create a separate FoundryVTT user account for the MCP server rather than using your own GM or player account. This provides better security and auditability.

In FoundryVTT:

1. Go to Configuration → User Management
2. Click Create User
3. Set a username (e.g., mcp-api) and a strong password
4. Assign the Assistant GM role (needed to read world data and roll dice)
5. Use this account’s credentials in your MCP configuration

Benefits:

• Chat messages and actions from the MCP server are clearly attributed to a separate user
• You can revoke access by disabling the API user without affecting your own account
• Limits blast radius if credentials are ever exposed

Installation

Run directly without installing — no clone needed:

bunx foundryvtt-mcp

Or with npx:

npx -y foundryvtt-mcp

Client Configuration

Claude Desktop / Claude Code

Add to your MCP configuration (claude_desktop_config.json or .mcp.json):

{
  "mcpServers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

VS Code

Add to your VS Code MCP settings:

{
  "servers": {
    "foundryvtt": {
      "command": "bunx",
      "args": ["foundryvtt-mcp"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "your_username",
        "FOUNDRY_PASSWORD": "your_password"
      }
    }
  }
}

Development Setup

For local development or contributing:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp
bun install