FoundryVTT MCP 서버

Foundry Virtual Tabletop(FoundryVTT) 를 위한 포괄적이고 프로덕션 등급의 Model Context Protocol(MCP) 서버입니다.

이 서버는 AI 어시스턴트(Claude Desktop, Claude Code, Oh My Pi, VS Code, Cursor 등)가 FoundryVTT 내부에서 완전한 기능을 갖춘 자율적인 공동 GM 및 GM 어시스턴트로 활동할 수 있게 합니다. 게임 메커니즘, 액터, 아이템, 토큰, 전투 인카운터, 캔버스 배치 객체(벽, 조명, 사운드, 템플릿, 드로잉, 노트, 타일), 플레이리스트, 매크로, 롤 테이블, 컴펜디움, 월드 설정, 실시간 캔버스 렌더링 전반에 걸쳐 완전한 읽기/쓰기 액세스를 제공합니다.

🌟 주요 하이라이트 및 기능 (111개 도구)

• 👁️ 실시간 이벤트 스트림 및 활동 로그 (watch_events): Socket.IO modifyDocument 및 동반 브리지 푸시를 통한 폴링 없는 이벤트 인식. AI DM 에이전트는 커서 기반 스트림(cursor, waitMs, excludeSelf, types, sceneId)에서 롱폴링하여 플레이어가 채팅하거나, 토큰을 이동하거나, 전투를 진행하거나, 문을 여닫거나, 대상을 선택할 때 즉시 반응할 수 있습니다.

• 🎲 게임 메커니즘 및 인터랙티브 채팅: 표준 또는 복잡한 드롭/킵 표기법(4d6kh3, 1d20r1)으로 주사위를 굴립니다. 동반 브리지를 통해 인터랙티브하고 클릭 가능한 채팅 카드를 Foundry 채팅 로그에 직접 굴려 게시합니다(roll_and_post).

• 🗺️ 전체 캔버스 및 공간 제어: 모든 캔버스 배치 객체 유형을 생성, 조회, 업데이트, 제거합니다:

  • 씬 리전 (v12 이상): 기하학적 모양(rectangle, circle, ellipse, polygon)과 자동화된 트리거 동작을 갖춘 create_region, delete_region, list_regions.

  • 벽 및 문: 일반 벽, 문(열기/닫기/잠그기), 비밀문, 창문, 에테르 벽, 사용자 지정 좌표(create_wall, list_walls, set_door_state).

  • 앰비언트 라이트: 좌표 또는 그리드 셀 배치, 어둡기/밝기 반경, 애니메이션 효과, 색상 임계값(create_light, update_light, delete_light, list_lights).

  • 앰비언트 사운드: 오디오 트랙, 반경, 볼륨, 반복 모드(create_sound, delete_sound, list_sounds).

  • 측정 템플릿: 콘, 원, 레이, 사각형 주문 효과 영역 표시와 방향 회전 및 색상(create_template, delete_template, list_templates).

  • 드로잉: 자유형 및 기하학적 모양, 선/채우기 스타일, 텍스트 주석(create_drawing, delete_drawing, list_drawings).

  • 맵 노트 및 핀: 저널 항목에 연결되거나 독립형 레이블로 표시되는 랜드마크 마커(create_note, delete_note, list_notes).

  • 타일 및 소품: 장식용 타일과 배경 배치(create_tile, delete_tile, list_tiles).

  • 캔버스 뷰포트 캡처: 좌표 그리드 오버레이([col,row])가 박힌 GM 캔버스 뷰포트를 capture_scene으로 스크린샷.

  • 대상 지정 및 애니메이션 핑: 애니메이션 카메라 핑(ping_canvas)으로 플레이어의 주의를 집중시키고 토큰 대상 지정 레티클을 보기/설정(set_target, get_targets).

• 🧙 토큰 및 액터 제어:

  • A* 경로 탐색 이동: 토큰이 벽을 우회하고 경로를 따라 닫힌 문을 자동으로 엽니다(move_token_pathfind).

  • 토큰 시야 및 조명: 시야 범위, 시야 모드, 어둡기/밝기 방출 광원, 시야 감지 각도를 구성합니다(update_token_vision).

  • 일반화된 ActiveEffects: 최상위 또는 합성 비연결 토큰 액터에서 속성 변경(key, mode, value, priority) 및 지속 시간(rounds, seconds, turns)을 갖는 기계적 버프/디버프를 생성, 업데이트, 삭제, 조회합니다(create_actor_effect, update_actor_effect, delete_actor_effect, list_actor_effects).

  • 상태 이상: 시스템에 구애받지 않는 상태 이상을 적용/제거합니다(apply_status_effect).

  • 컴펜디움 액터 및 아이템 가져오기: 항목별 오류 자동 복구와 함께 컴펜디움 팩에서 전체 NPC/몬스터 문서를 가져오거나(import_compendium_actor), 특정 아이템을 액터 인벤토리로 가져옵니다(create_actor_item).

  • 시스템 속성 변경: JSON 병합 패치를 사용하여 액터 시스템 데이터(HP, 임시 HP, 화폐, 자원, 주문 슬롯)를 패치합니다(update_actor_attributes).

• ⚔️ 전투 인카운터 관리: 인카운터 생성, 토큰에서 전투원 시드, 이니셔티브 순서 관리, 턴/라운드 진행, 활성 전투원 추적, 게임 시계 일시정지/재개(set_pause), 인카운터 종료.

• 📜 월드 문서 및 조직:

  • 폴더: 액터, 아이템, 저널, 씬의 계층적 폴더 구조 관리(create_folder, list_folders).

  • 매크로: 스크립트/채팅 매크로 조회, 생성, 삭제(create_macro, list_macros, delete_macro).

  • 플레이리스트 및 오디오: 다중 트랙 플레이리스트 생성, 재생 제어(재생, 일시정지, 정지), 트랙 상태 조정(create_playlist, set_playlist_state, list_playlists).

  • 롤 테이블: 자동 순차 범위 분배(1dN)로 테이블 생성, 실시간 결과 추첨(create_roll_table, roll_table, list_roll_tables).

  • 문서 소유권 및 사용자 역할: 세분화된 문서 권한(set_document_ownership)과 자기 강등 잠금 보호 장치가 있는 사용자 역할(set_user_role)을 구성합니다.

  • 월드 설정: 핵심 엔진 손상에 대한 내장 보호 기능으로 모듈 및 시스템 설정을 안전하게 조회/업데이트합니다(get_world_setting, set_world_setting).

  • 에셋 업로드: 네이티브 FilePicker 또는 로컬 파일시스템을 통해 이미지, 토큰, 오디오를 Foundry의 Data/ 저장소에 직접 업로드합니다(upload_asset).

• 🌫️ 씬, 날씨 및 탐험 관리: 활성 씬 전환, 어둠 수준 조정, 전역 조명 전환, 환경 날씨 효과 설정(set_scene_weather), 전쟁 안개 탐험 재설정(reset_fog).

• 🔍 규칙 및 컴펜디움 검색: 상황별 스니펫과 함께 월드 문서, 컴펜디움 팩, 규칙 텍스트를 검색합니다(search_compendium_content, lookup_rule).

Related MCP server: Foundry VTT MCP Bridge

🏗️ 아키텍처

서버는 실시간 응답성과 깊은 게임 엔진 통합을 제공하기 위해 하이브리드 아키텍처를 사용합니다.

┌─────────────────────────────────────────────────────────────┐
│                    AI Assistant / MCP Client                │
│             (Claude Desktop, Oh My Pi, VS Code)             │
└──────────────────────────────┬──────────────────────────────┘
                               │ MCP (stdio)
┌──────────────────────────────▼──────────────────────────────┐
│                    FoundryVTT MCP Server                    │
├──────────────────────────────┬──────────────────────────────┤
│  In-Memory World Cache       │  A* Pathfinding Router       │
│  (Live Socket.IO Sync)       │  Dice Notation Engine        │
└──────────────┬───────────────┴──────────────┬───────────────┘
               │ Socket.IO (Port 30000)       │ WebSocket (Port 31415)
               │ (modifyDocument / Events)    │ (Bridge Protocol)
┌──────────────▼──────────────────────────────▼───────────────┐
│                    FoundryVTT Game Engine                   │
│  ┌────────────────────────┐    ┌─────────────────────────┐  │
│  │   Active World & Data  │    │  Companion Module       │  │
│  │   (Actors, Scenes, …)  │    │  (foundryvtt-mcp-bridge)│  │
│  └────────────────────────┘    └─────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘

1. Socket.IO 기본 연결: 인증된 사용자(mcp-api)로 FoundryVTT에 연결됩니다. 월드 상태를 자동으로 동기화하고 캐시하여 modifyDocument 프로토콜을 통한 즉각적인 조회와 고빈도 문서 변경을 가능하게 합니다.

2. 동반 모듈 브리지 (foundryvtt-mcp-bridge): 브라우저에서 실행되는 경량 Foundry 모듈로, 캔버스 바인딩 작업(PIXI 캔버스 스크린샷 및 그리드 오버레이, 네이티브 Roll 채팅 카드 렌더링, 문서 스키마 내부 조사, 컴펜디움 아이템 추출)을 실행합니다.

3. 선택적 REST API 모듈: 로컬 REST 모듈이 설치된 경우 서버 진단, 로그 검색, 상태 보고를 제공합니다.

🚀 빠른 시작

1. 사전 요구 사항

• Node.js 18+ 또는 Bun

• 활성 월드가 실행 중인 FoundryVTT v11+ / v12+

• Gamemaster 또는 Assistant GM 역할을 가진 전용 Foundry 사용자 계정

2. 전용 Foundry 사용자 구성

FoundryVTT에서:

1. Configuration → User Management 열기

2. Create User 클릭

3. 사용자 이름: mcp-api, 비밀번호: mcp(또는 원하는 값) 설정

4. 역할: Gamemaster(또는 쓰기 권한이 활성화된 Assistant GM)

3. 동반 모듈 설치 (권장)

이 저장소의 foundry-module 폴더를 FoundryVTT Data/modules/ 디렉토리에 복사합니다:

# Windows
cp -r foundry-module "%LOCALAPPDATA%/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# macOS
cp -r foundry-module "~/Library/Application Support/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

# Linux
cp -r foundry-module "~/.local/share/FoundryVTT/Data/modules/foundryvtt-mcp-bridge"

FoundryVTT에서 Manage Modules로 이동하여 FoundryVTT MCP Bridge를 활성화합니다.

⚙️ 구성 및 클라이언트 설정

환경 변수

Claude Desktop 구성

claude_desktop_config.json에 추가:

{
  "mcpServers": {
    "foundryvtt": {
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      }
    }
  }
}

Oh My Pi 구성

~/.omp/agent/mcp.json(또는 ~/.omp/mcp.json)에 추가:

{
  "mcpServers": {
    "foundryvtt": {
      "type": "stdio",
      "command": "node",
      "args": ["<PATH_TO_REPO>/dist/index.js"],
      "env": {
        "FOUNDRY_URL": "http://localhost:30000",
        "FOUNDRY_USERNAME": "mcp-api",
        "FOUNDRY_PASSWORD": "mcp",
        "FOUNDRY_WRITE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_ENABLED": "true",
        "FOUNDRY_MODULE_BRIDGE_PORT": "31415"
      },
      "timeout": 60000
    }
  }
}

🛠️ 도구 카탈로그 (111개 도구)

1. 실시간 이벤트 인식

• watch_events — 커서 기반 활동 로그(cursor, waitMs, limit, kinds, types, actions, sceneId, excludeSelf)를 롱폴링하여 폴링 없이 문서 브로드캐스트와 캔버스 활동을 캡처합니다.

2. 캔버스 및 공간 배치 객체

• create_region / delete_region / list_regions — 기하학적 모양(rectangle, circle, ellipse, polygon)과 자동화된 동작을 갖춘 씬 리전(v12 이상) 관리.

• create_wall / delete_wall / list_walls / set_door_state — 완전한 벽과 문 기하학 관리.

• create_light / update_light / delete_light / list_lights — 앰비언트 조명 제어(반경, 색상, 애니메이션).

• create_sound / delete_sound / list_sounds — 캔버스 씬에 앰비언트 오디오 배치.

• create_template / delete_template / list_templates — 주문 및 효과 영역 템플릿.

• create_drawing / delete_drawing / list_drawings — 맵 모양, 구역, 텍스트 주석.

• create_note / delete_note / list_notes — 맵 핀 및 랜드마크 마커.

• create_tile / delete_tile / list_tiles — 장식용 타일 및 맵 소품.

• capture_scene — 그리드 좌표 오버레이가 박힌 활성 씬 캔버스를 스크린샷.

• ping_canvas — 특정 픽셀 좌표에 애니메이션 캔버스 핑을 발생시킵니다.

• find_open_cells — 토큰/소품 배치에 적합한 차단되지 않은 그리드 셀을 씬에서 검색.

• list_scene_assets — 파싱된 태그와 크기와 함께 맵 배경, 토큰 아트, 오디오 파일을 발견.

• upload_asset — FilePicker 또는 로컬 파일시스템을 통해 이미지/오디오 파일을 Foundry의 Data/ 디렉토리에 업로드.

3. 토큰 및 이동

• spawn_token — 사용자 지정 크기, 고도 및 좌표로 씬에 액터 토큰을 배치합니다.

• delete_token — 기본 액터를 삭제하지 않고 씬에서 토큰을 제거합니다.

• list_tokens — 활성 또는 특정 씬에 배치된 토큰을 나열합니다.

• move_token — 토큰을 정확한 픽셀 좌표로 순간이동합니다.

• move_token_pathfind — 자동 문 열림과 함께 벽 주변 A* 장애물 회피를 사용하여 토큰을 이동합니다.

• move_tokens — 여러 토큰을 동시에 일괄 이동합니다.

• set_target / get_targets — 연결된 사용자 간 토큰 대상 지정 레티클을 설정하고 확인합니다.

• update_token_vision — 시야 범위, 시야 모드, 희미한/밝은 방출 조명 및 각도를 구성합니다.

• apply_status_effect — 간단한 상태 조건(prone, stunned, blinded, invisible 등)을 전환합니다.

4. 액터 및 인벤토리

• create_world_actor / create_full_actor / delete_world_actor — 액터 문서를 생성하고 삭제합니다.

• import_compendium_actor — 포함된 아이템과 자동 오류 복구 기능을 갖춘 컴펜디움 팩에서 전체 NPC/몬스터를 가져옵니다.

• search_actors — 커서 페이지네이션을 지원하여 이름과 유형으로 액터를 검색합니다.

• get_actor_details — 액터 시스템 데이터, 통계, 속성 및 체력을 검색합니다.

• update_actor_attributes — 점 경로(attributes.hp.value, currency.gp)를 사용하여 중첩된 시스템 데이터를 패치합니다.

• get_actor_inventory — 전체 시스템 속성을 가진 소유 아이템을 나열합니다.

• create_actor_item — 인라인 아이템을 생성하거나 컴펜디움 팩에서 직접 가져옵니다(source: { type: 'compendium', compendiumId, itemId }).

• update_actor_item — 소유 아이템에 JSON 병합 패치를 적용합니다.

• delete_actor_item — 액터 인벤토리에서 특정 아이템을 삭제합니다.

• create_actor_effect / update_actor_effect / delete_actor_effect / list_actor_effects — 최상위 또는 합성 비연결 토큰 액터에 기계적 변경(key, mode, value, priority) 및 지속 시간을 적용하는 범용 ActiveEffects입니다.

5. 전투 인카운터

• start_combat — 인카운터를 생성하고 씬 토큰에서 전투원을 시드합니다.

• get_combat_state — 전투원 턴 순서, HP, AC 및 라운드 번호를 검색합니다.

• set_initiative — 전투원의 선제권 값을 설정하고 턴을 재정렬합니다.

• next_turn — 턴 추적기를 진행합니다(라운드 증가 처리 및 패배한 전투원 건너뛰기).

• set_pause — 게임 시계를 일시 중지하거나 재개합니다.

• end_combat — 활성 인카운터를 종료합니다.

6. 월드 문서 및 구성

• list_folders / create_folder — 액터, 아이템, 저널 및 씬을 중첩 폴더로 구성합니다.

• list_macros / create_macro / delete_macro — 스크립트 및 채팅 매크로 문서를 관리합니다.

• list_playlists / create_playlist / set_playlist_state / delete_playlist — 오디오 재생 목록 및 사운드 제어.

• create_roll_table / delete_roll_table / roll_table / list_roll_tables — 테이블 생성 및 결과 굴림.

• get_world_setting / set_world_setting — 핵심 보호 기능으로 시스템/모듈 설정을 확인하고 수정합니다.

• set_document_ownership — 세분화된 문서 권한(none, limited, observer, owner)을 구성합니다.

• get_users / set_user_role — 연결된 사용자를 나열하고 자기 강등 잠금 방지 기능으로 권한 역할을 변경합니다.

• create_journal_entry / get_journal / search_journals / delete_journal_entry — 세션 노트와 세계관 정보를 관리합니다.

7. 씬, 날씨 및 탐험

• create_scene / delete_scene / get_scene_info / switch_scene — 씬 생성 및 플레이어 활성화.

• set_scene_weather — 날씨 효과를 설정하거나 해제합니다(rain, snow, fog, "").

• set_scene_lighting — 주변 어둠 수준 및 전역 조명 설정.

• reset_fog — 활성 씬의 전쟁 안개 탐험을 초기화합니다.

8. 게임 메커니즘 및 브리지 도구

• roll_dice — 로컬 수학 주사위 공식 평가.

• roll_and_post — Foundry의 기본 엔진을 통해 공식을 평가하고 대화형 채팅 카드를 게시합니다.

• lookup_rule — 스니펫 미리보기와 함께 규칙을 위해 월드 저널 및 시스템 컴펜디움 팩을 검색합니다.

• get_document_schema — 액터 및 아이템 유형에 대한 게임 시스템 DataModel 스키마를 검사합니다.

• search_compendium_content — 컴펜디움 팩 문서 및 저널 페이지 내부를 심층 검색합니다.

• send_chat_message / get_chat_messages — Foundry 채팅 로그에 메시지를 게시하고 읽습니다.

• generate_npc / generate_loot — 즉시 절차적 생성기.

9. 진단 및 로깅

• get_health_status / get_system_health — 연결 및 서버 상태 메트릭.

• get_recent_logs / search_logs — 서버 로그 및 오류 스택 추적을 검사합니다.

• diagnose_errors — 최근 오류를 분석하여 우선순위가 지정된 해결 제안을 제공합니다.

• refresh_world_data — 캐시된 월드 상태 스냅샷을 강제로 다시 가져옵니다.

🧪 개발 및 테스트

# Install dependencies
npm install

# Compile TypeScript
npm run build

# Run complete unit test suite (713 tests)
npm test

# Run linter and formatting checks
npm run lint

# Start server in development watch mode
npm run dev

📄 라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다.