FoundryVTT MCP 서버

FoundryVTT와 통합되는 Model Context Protocol(MCP) 서버로, AI 어시스턴트가 자연어를 통해 테이블톱 게임 세션과 상호작용할 수 있게 해줍니다.

기능

• 주사위 굴리기 — 모든 수식이 가능한 표준 RPG 표기법

• 데이터 조회 — 액터, 아이템, 씬, 저널 검색 및 확인

• 게임 상태 — 전투 추적, 채팅 메시지, 사용자 접속 상태

• 콘텐츠 생성 — NPC, 전리품 테이블, 규칙 조회

• 월드 검색 — 모든 게임 엔티티에 대한 전체 텍스트 검색

• 실시간 연결 — Socket.IO가 연결 시 전체 월드 상태를 로드

• MCP 리소스 — 직접 데이터 접근을 위한 foundry:// URI

• 진단 — 선택적 서버 상태 모니터링(REST API 모듈 필요)

Related MCP server: FoundryVTT MCP Server

빠른 시작

사전 요구 사항

• Node.js 18+ (또는 Bun)

• 활성 월드가 실행 중인 FoundryVTT 서버

• MCP 호환 AI 클라이언트(Claude Desktop, Claude Code, VS Code 등)

권장: 전용 API 사용자 생성

MCP 서버에는 자신의 GM 또는 플레이어 계정 대신 별도의 FoundryVTT 사용자 계정을 만드는 것이 좋습니다. 이렇게 하면 보안과 감사 추적성이 향상됩니다.

FoundryVTT에서:

1. 구성 → 사용자 관리로 이동

2. 사용자 생성 클릭

3. 사용자 이름(예: mcp-api)과 강력한 비밀번호 설정

4. Assistant GM 역할 할당(월드 데이터 읽기와 주사위 굴리기에 필요)

5. MCP 구성에서 이 계정의 자격 증명 사용

이점:

• MCP 서버의 채팅 메시지와 작업이 별도의 사용자로 명확하게 표시됨

• API 사용자를 비활성화하여 접근을 취소할 수 있으며 자신의 계정에는 영향 없음

• 자격 증명이 노출되어도 피해 범위를 제한함

설치

설치 없이 직접 실행 — 클론 불필요:

bunx foundryvtt-mcp

또는 npx 사용:

npx -y foundryvtt-mcp

클라이언트 구성

Claude Desktop / Claude Code

MCP 구성(claude_desktop_config.json 또는 .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

VS Code MCP 설정에 추가:

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

개발 환경 설정

로컬 개발 또는 기여를 위해:

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

설정 마법사가 FoundryVTT 서버를 감지하고, 연결을 테스트하며, .env 구성을 생성합니다.

수동으로 구성하려면 구성 가이드를 참조하세요.

환경 변수

사용법

AI 어시스턴트에게 다음과 같이 요청하세요:

• "공격 판정으로 1d20+5 굴려줘"

• "이 씬의 모든 NPC를 보여줘"

• "현재 전투 이니셔티브 순서가 어떻게 되지?"

• "드래곤과 관련된 모든 것을 월드에서 검색해줘"

• "랜덤 NPC 상인을 생성해줘"

사용 가능한 도구

데이터 접근

• search_actors — 캐릭터, NPC, 몬스터 찾기

• get_actor_details — 상세 캐릭터 정보

• search_items — 장비, 주문, 소모품 찾기

• get_scene_info — 현재 씬 세부 정보

• search_journals — 메모와 핸드아웃 검색

• get_journal — 특정 저널 항목 검색

• get_users — 사용자, 역할, 실시간 온라인 상태 나열

• get_combat_state — 전투 상태 및 이니셔티브 순서

• get_chat_messages — 최근 채팅 기록

쓰기 작업(FOUNDRY_WRITE_ENABLED=true 필요)

게임 상태 변경은 기본적으로 비활성화되어 있습니다. 인증된 세션을 통해 Socket.IO modifyDocument 프로토콜을 사용하며, 연결된 사용자에게 GM/소유자 권한이 필요합니다. 활성화하려면 FOUNDRY_WRITE_ENABLED=true로 설정하세요.

• start_combat — 새 전투 시작, 토큰에서 전투원 시드(기존 전투를 확인하지 않음 — 활성 전투 중 호출하면 두 번째 전투가 생성됨)

• next_turn — 활성 전투를 다음 턴으로 진행(다음 라운드로 순환)

• end_combat — 활성 전투 종료(삭제)

• set_initiative — 활성 전투에서 전투원의 이니셔티브 설정, 재정렬로 전투원이 이동하면 턴 마커도 함께 이동

• move_token — 토큰을 해당 씬의 새 x/y 좌표로 이동

• apply_status_effect — 토큰의 액터에 상태 조건(예: 엎드림, 기절) 적용 또는 제거

• update_actor_attributes — 액터의 system 속성(HP, 화폐, 주문 슬롯 등) 패치

• create_actor_item — 액터에 인라인 아이템 추가

• update_actor_item — 액터의 아이템에 JSON 병합 패치 적용

• delete_actor_item — 액터에서 아이템 제거

• create_journal_entry — 하나 이상의 텍스트 페이지로 저널 항목 생성 (기본적으로 GM 전용; visibility를 전달하면 플레이어가 읽을 수 있음)

월드

• search_world — 모든 게임 엔티티에 대한 전체 텍스트 검색

• get_world_summary — 현재 월드 상태 개요

• refresh_world_data — FoundryVTT에서 월드 데이터 다시 로드; 연결이 끊긴 후 필요하며, 놓친 업데이트는 캐시에 재생되지 않음

게임 메커니즘

• roll_dice — 주사위 굴리기; +/-로 연결된 주사위 용어(NdS)와 정수, 지원되지 않는 표기법(4d6kh3, 1d20r1, *)은 버리지 않고 거부. 괄호가 유일한 전송 차이: FOUNDRY_API_KEY가 설정되면 FoundryVTT가 평가하고, 그렇지 않으면 로컬 롤러가 거부

• lookup_rule — 스텁: 템플릿화된 자리 표시자를 반환하며, 규칙 소스를 참조하지 않음

콘텐츠 생성

• generate_npc — NPC 텍스트 생성(월드에 기록되지 않음)

• generate_loot — 레벨에 대한 보물 텍스트 생성(월드에 기록되지 않음)

진단(REST API 모듈 필요)

• get_recent_logs — 필터링된 FoundryVTT 로그 검색

• search_logs — 패턴으로 로그 검색, 일치하는 항목 나열

• get_system_health — 버전, 사용자/모듈 수, 메모리 및 로그 오류 수가 포함된 서버 상태 (CPU 또는 디스크 메트릭 없음)

• diagnose_errors — 스텁: 고정된 "오류 없음" 요약 반환

• get_health_status — 종합 상태 진단; 캐시가 실시간 변경을 따라가지 못하면 월드 스냅샷에 플래그 지정

사용 가능한 리소스

• foundry://actors — 월드의 모든 액터

• foundry://items — 월드의 모든 아이템

• foundry://scenes — 모든 씬

• foundry://scenes/current — 현재 활성 씬

• foundry://journals — 모든 저널 항목

• foundry://users — 온라인 사용자

• foundry://combat — 활성 전투 상태; combatants는 이니셔티브 순서이므로 combat.turn이 직접 인덱싱함

• foundry://world/settings — 월드 및 캠페인 설정

• foundry://system/diagnostics — 시스템 진단(REST API 모듈 필요)

문제 해결

연결 및 설정 도우미는 소스 트리에 포함되어 있습니다(게시된 bin 아님). 개발 체크아웃에서 실행하세요:

git clone https://github.com/laurigates/foundryvtt-mcp.git
cd foundryvtt-mcp && bun install
bun run test-connection   # Probe FoundryVTT connectivity
bun run setup-wizard      # Re-run interactive setup

상세 가이드: TROUBLESHOOTING.md

개발

bun run build          # Compile TypeScript and make dist/index.js executable
bun run dev            # Development mode with hot reload
bun test               # Unit tests (Vitest)
bun run test:e2e       # E2E tests (Playwright)
bun run lint           # Lint code (Biome)
bun run smoke          # Startup smoke test against the local build
bun run smoke:pack     # Pack-and-install smoke test (mirrors what npx consumers get)

프로젝트 구조, 도구 추가, 테스트 및 빌드에 대해서는 개발 가이드를 참조하세요.

로드맵

완료 및 계획된 기능은 기능 추적기를 참조하세요.

기여

CONTRIBUTING.md를 참조하세요.

라이선스

MIT 라이선스 — 자세한 내용은 LICENSE를 참조하세요.

지원

• 이슈: GitHub Issues

• Discord: FoundryVTT Discord #api-development

• 문서: FoundryVTT API

감사의 말

• 훌륭한 VTT 플랫폼을 만든 FoundryVTT 팀

• Model Context Protocol을 만든 Anthropic

• 영감과 피드백을 준 테이블톱 게이밍 커뮤니티