Foundry VTT MCP 브리지

Foundry VTT를 Claude Desktop에 연결하여 MCP(Model Context Protocol)를 통해 AI 기반 캠페인 관리를 수행하세요. 현재 Dungeons and Dragons 5판(D&D 5e)과 Pathfinder 2판(PF2E)을 지원합니다. 대부분의 MCP 도구는 시스템에 구애받지 않지만, 캐릭터 생성 및 컴펜디움 도구는 D&D 5e 및 PF2E에서만 작동합니다.

개요

Foundry MCP 브리지를 사용하면 Foundry VTT 게임 데이터와 자연스러운 AI 대화가 가능합니다:

• 퀘스트 생성: 세계관과 저널에 존재하는 내용을 통합하여 프롬프트로부터 퀘스트 생성

• 캐릭터 관리: 캐릭터 능력치, 기술 및 정보 조회

• 컴펜디움 검색: 자연어를 사용하여 아이템, 주문, 생명체 검색

• 콘텐츠 생성: 간단한 프롬프트로 액터, NPC, 퀘스트 저널 생성

• 장면 정보: 현재 장면 데이터 및 세계관 세부 정보 액세스

• 주사위 조정: 플레이어 타겟팅을 포함한 대화형 주사위 굴리기 요청

• 캠페인 관리: 다단계 퀘스트 및 캠페인 추적

• 지도 생성: 프롬프트로부터 지도를 생성하고, 선택 사항인 ComfyUI 구성 요소를 사용하여 Foundry VTT 장면에 자동으로 업로드

이 프로젝트는 Claude Code의 도움을 받아 제작되었습니다. 이 프로젝트가 마음에 드신다면 Patreon에서 후원을 고려해 주세요.

Related MCP server: Coreflux MCP Server

설치

사전 요구 사항

• Foundry VTT v13

• MCP를 지원하는 Claude Desktop

• Windows(자동 설치 프로그램용) 또는 Node.js 18+(수동 설치용)

옵션 1: Windows 설치 프로그램

Windows 설치 프로그램 가이드 영상

1. Releases에서 최신 FoundryMCPServer-Setup-vx.x.x.exe를 다운로드합니다.

2. 설치 프로그램을 실행하면 다음 작업이 수행됩니다:

   • 번들로 제공되는 Node.js 런타임과 함께 MCP 서버 설치

   • Claude Desktop MCP 서버 설정 구성

   • 선택적으로 Foundry 모듈 및 ComfyUI 지도 생성 기능을 VTT 설치 경로에 설치

   • 설치 중 GPU 유형에 맞는 Cuda 버전 선택

3. Claude Desktop을 재시작합니다.

4. Foundry 모듈 관리에서 "Foundry MCP Bridge"를 활성화합니다.

옵션 2: Mac 설치 프로그램

1. Releases에서 최신 FoundryMCPServer-vx.x.x.dmg를 다운로드합니다.

2. dmg 내부의 패키지 설치 프로그램을 실행하면 다음 작업이 수행됩니다:

   • DMG를 열고 PKG 설치 프로그램을 더블 클릭

   • Claude Desktop MCP 서버 설정 구성

   • 선택적으로 Foundry 모듈 및 ComfyUI 지도 생성 기능을 Foundry VTT 설치 경로에 설치

3. Claude Desktop을 재시작합니다.

4. Foundry 모듈 관리에서 "Foundry MCP Bridge"를 활성화합니다.

옵션 3: 수동 설치

Foundry 모듈 설치

1. Foundry VTT v13을 엽니다.

2. Foundry 애드온 메뉴에서 모듈 설치를 선택합니다.

3. 창 하단에 매니페스트 URL(https://github.com/adambdooley/foundry-vtt-mcp/blob/master/packages/foundry-module/module.json)을 추가하고 설치를 클릭합니다.

4. 모듈 관리에서 "Foundry MCP Bridge"를 활성화합니다.

   • 모듈 ID나 폴더 이름을 변경하지 마십시오. MCP 백엔드와 Claude 통합 기능 모두 모듈이 foundry-mcp-bridge라는 디렉토리에 있기를 기대합니다. module.json에서 ID를 변경하면 소켓 라우팅이 깨져 Claude가 백엔드를 인식하지 못하게 됩니다.

MCP 서버 설치

# 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

Claude Desktop 구성

Claude Desktop 구성(claude_desktop_config.json) 파일에 다음을 추가합니다:

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

Claude Desktop을 시작하면 MCP 서버가 시작됩니다.

시작하기

1. Foundry VTT를 시작하고 월드를 로드합니다.

2. Claude Desktop을 엽니다.

3. 현재 로드된 Foundry 월드에 대해 Claude와 대화합니다.

사용 예시

연결 후 Claude Desktop에 다음과 같이 질문해 보세요:

• "내 캐릭터 Clark의 능력치를 보여줘"

• "조우를 위해 CR 12인 인간형 생명체를 모두 찾아줘"

• "실종된 마을 사람들을 조사하는 퀘스트를 만들어줘"

• "Tulkas의 은신 판정을 굴려줘"

• "현재 Foundry 장면에 무엇이 있지?"

• "Foundry에 Riverside Cottage 작은 지도를 만들어줘"

기능

• 36개의 MCP 도구: Claude가 Foundry와 상호작용할 수 있도록 지원

• 캐릭터 관리: 능력치, 기술, 인벤토리 및 상세 엔티티 정보 액세스

• 토큰 조작: 토큰 이동, 업데이트, 삭제 및 상태 조건 관리

• 향상된 컴펜디움 검색: CR, 유형, 능력치 등으로 즉시 필터링

• 콘텐츠 생성: 액터, NPC, 퀘스트 저널 생성

• 캠페인 관리: 진행 상황 대시보드가 포함된 다단계 퀘스트 추적

• 대화형 주사위 시스템: Claude에서 플레이어에게 다양한 주사위 굴리기 요청 전송

• 액터 소유권: 캐릭터 및 토큰에 대한 플레이어 권한 관리

• GM 전용: MCP 브리지는 게임 마스터 사용자에게만 연결됨

• 지도 생성: 프롬프트로부터 전투 지도를 생성하는 휴대용 ComfyUI 백엔드

• 원격 연결: 브라우저를 통해 시작되는 WebRTC 연결(Google Chrome에서 테스트됨)을 MCP 서버 및 ComfyUI에 연결

• Windows 및 Mac 설치 프로그램: Claude Desktop용 Foundry MCP 서버, Foundry VTT 모듈, 종속성이 포함된 ComfyUI 백엔드의 자동 설치

MCP 도구

• 1 get-world-info

• 2 list-scenes

• 3 get-current-scene

• 4 get-available-conditions

• 5 list-compendium-packs

• 6 list-characters

• 7 get-character

• 8 search-character-items

• 9 get-character-entity

• 10 get-token-details

• 11 toggle-token-condition (add)

• 12 toggle-token-condition (remove)

• 13 update-token

• 14 search-compendium

• 15 get-compendium-item

• 16 get-compendium-entry-full

• 17 list-creatures-by-criteria

• 18 list-journals

• 19 create-quest-journal

• 20 update-quest-journal

• 21 search-journals

• 22 link-quest-to-npc

• 23 list-actor-ownership

• 24 assign-actor-ownership

• 25 remove-actor-ownership

• 26 move-token

• 27 use-item

• 28 request-player-rolls

• 29 generate-map

• 30 check-map-status

• 31 cancel-map-job

• 32 switch-scene

• 33 create-actor-from-compendium

• 34 list-dsa5-archetypes

• 35 create-dsa5-character-from-archetype

• 36 create-campaign-dashboard

설정

• Enhanced Creature Index: Enhanced Index 버튼을 구성하면 Enhanced Creature Index 하위 메뉴로 이동합니다(아래 세부 정보 참조).

• Map Generation Service Configuration: Map Generation 버튼을 구성하면 Map Generation Service 하위 메뉴로 이동합니다(아래 세부 정보 참조).

• Enable MCP Bridge: 기본적으로 체크되어 있어야 하며 상태가 연결됨으로 표시되어야 합니다. 애드온 자체를 비활성화하지 않고도 게임 내에서 MCP 브리지 연결을 끄는 데 사용할 수 있습니다.

• Connection Type: 연결 유형을 자동으로 감지하려면 Auto로 설정할 수 있습니다. 인터넷 연결을 위한 WebRTC 또는 로컬 연결을 위한 Websocket으로 강제 설정할 수도 있습니다.

• Websocket Server Host: Claude Desktop MCP 서버 위치의 IP 주소입니다. 로컬 네트워크 Websocket 연결에만 사용됩니다. 원격 서버는 WebRTC를 사용합니다. 기본값은 localhost입니다.

• Allow Write Operations: Claude가 월드 콘텐츠를 변경하지 못하도록 방지하고 읽기 전용으로 제한합니다.

• Max Actors Per Request: 단일 요청으로 너무 많은 액터가 생성되는 것을 방지하는 안전 장치입니다. 여러 요청으로 생성되는 캐릭터 수까지 제한하지는 않습니다.

• Show Connection Messages: Foundry MCP 브리지의 연결 배너 메시지를 끌 수 있습니다.

• Auto-Reconnect on Disconnect: 연결이 끊기면 자동으로 재연결을 시도합니다.

• Connection Check Frequency: 연결 상태를 확인하는 빈도입니다.

Enhanced Creature Index 하위 메뉴

• Rebuild Creature Index: 컴펜디움의 변경 사항과 동기화되지 않거나 문제가 발생할 경우 생명체 인덱스를 다시 빌드합니다.

• Enable Enhanced Creature Index: Claude가 더 나은 검색을 위해 월드 파일에 추가 메타데이터를 빌드하므로 이 옵션은 켜두는 것이 좋습니다.

• Auto-Rebuild Index on Pack Changes: 아직 완전히 테스트되지 않은 실험적 기능입니다.

Map Generation Service 하위 메뉴

• Service Status: 상태 확인, 서비스 시작, 서비스 중지 버튼이 있습니다. 이 버튼들은 Claude Desktop 애플리케이션에 의해 시작되는 ComfyUI 백엔드와 Foundry MCP 브리지 간의 연결을 모니터링하고 제어하는 데 도움이 됩니다.

• Auto-start Map Generation Service: Foundry 월드 시작 시 ComfyUI 서비스 연결을 자동으로 연결할지 여부를 제어합니다.

• Generation Quality: ComfyUI 내 SDXL 체크포인트로 생성된 지도의 품질을 제어합니다. Low는 8단계 생성, Medium은 20단계, High는 35단계를 사용합니다. 이 이미지 생성에 사용된 D&D Battlemaps SDXL Upscale v1.0 체크포인트는 35단계 사용을 권장하지만, 저사양 GPU나 CUDA가 없는 GPU에서는 생성에 몇 분이 소요될 수 있습니다. 이 옵션을 통해 품질을 희생하면서 지도를 더 빠르게 생성할 수 있습니다.

아키텍처

Claude Desktop ↔ MCP Protocol ↔ MCP Server ↔ WebSocket ↔ Foundry Module ↔ Foundry VTT
                                     ↓
                              ComfyUI Service
                              (AI Map Generation)

• Foundry Module: Foundry VTT 내에서 안전한 데이터 액세스 제공

• MCP Server: Claude Desktop 통신을 처리하는 외부 Node.js 서버

• Map Generation Service: Claude Desktop에 의해 생성되는 헤드리스 ComfyUI 백엔드

• API 키 불필요: 기존 Claude Desktop 구독 사용

보안 및 권한

• GM 전용 액세스: 모든 기능이 게임 마스터 사용자로 제한됨

• 구성 가능한 권한: Claude가 액세스하고 수정할 수 있는 데이터 제어

• 세션 기반 인증: Foundry의 내장 인증 시스템 사용

시스템 요구 사항

• Foundry VTT: 버전 13

• Claude Desktop: MCP를 지원하는 최신 버전

• Claude Pro/Max 플랜: MCP 서버 연결에 필요

• 운영 체제: Windows 10/11(설치 프로그램), 또는 Node.js 18+가 설치된 기타 OS/수동 Windows 설치

• GPU 요구 사항: 최소 8GB VRAM을 갖춘 GPU

스키마 스모크 테스트

MCP 스키마 스모크 테스트는 도구 스키마가 올바르게 로드되는지, 그리고 지나치게 엄격한 additionalProperties 기본값을 강제하지 않는지 확인합니다.

npm -w @foundry-mcp/server run build
npm run test:mcp:schema

지원 및 개발

• 이슈: GitHub Issues에 버그 보고

• YouTube 채널: 업데이트 및 튜토리얼 구독

• 문서: TypeScript로 제작되었으며 포괄적인 문서 포함

• 라이선스: MIT 라이선스(설치 프로그램용 번들 구성 요소에 대한 추가 타사 라이선스 포함)