Back to Home
darkbard81 icon

foundryvtt-mcp-relay

Verified Safe

by darkbard81

Overview

Relays events and messages between LLMs, the MCP server, and Foundry VTT, incorporating AI-powered text-to-speech and image generation.

Installation

Run Command
podman run -d --name fvtt-mcp --env-file .env -p 3000:3000 ghcr.io/darkbard81/fvtt-mcp:latest

Environment Variables

  • MCP_SERVER_API_KEY
  • AUDIO_MODEL
  • AUDIO_OUTPUT_DIR
  • AUDIO_PATH
  • BASE_URL
  • CLIENT_CLEANUP_INTERVAL_MS
  • CORS_URL
  • DB_TYPE
  • FOUNDRY_DATA_PATH
  • GH_PROJECT
  • GH_TAG
  • GITHUB_CLIENT_ID
  • GITHUB_CLIENT_SECRET
  • GITHUB_REDIRECT_URI
  • CHATGPT_REDIRECT_URI
  • GOOGLE_GENAI_API_KEY
  • GOOGLE_GENAI_PROJECT_ID
  • GOOGLE_GENAI_PROJECT_LOCATION
  • HOST
  • IMAGE_MODEL
  • IMAGE_OUTPUT_DIR
  • IMAGE_PATH
  • INSTANCE_ID
  • LOG_LEVEL
  • MCP_PATH
  • MODULE_VERSION
  • NODE_ENV
  • PORT
  • WEBSOCKET_PING_INTERVAL_MS
  • WS_PATH
  • WIDGET_AV_WS_PATH

Security Notes

The server uses environment variables for sensitive API keys (MCP_SERVER_API_KEY, GOOGLE_GENAI_API_KEY, GitHub OAuth secrets), which is good practice. Client connections are authenticated using an API key via WebSocket. It implements a basic OAuth flow for GitHub, storing tokens in a local file (`token-store.json`) which requires secure host system configuration. A payload deduplication middleware is used to prevent replay attacks or accidental duplicate requests. Content Security Policy headers are defined for the UI widgets, limiting resource and connection domains to `https://mcp.krdp.ddns.net`, which enhances client-side security but implies the server needs to run on this specific domain or have the CSP updated. The WebSocket for the A/V widget (`/widget-av`) does not appear to have explicit authentication in its `onConnection` handler, potentially allowing unauthenticated connections, though the `set-av-state` tool still requires MCP authentication. Statically served AI-generated assets (audio, images) require the `FOUNDRY_DATA_PATH` to be securely configured. Wide-open CORS (`*`) is possible if configured, which is a risk.

Similar Servers

Stats

Interest Score0
Security Score8
Cost ClassHigh
Stars0
Forks0
Last Update2026-01-01

Tags

Node.jsTypeScriptFoundry VTTLLM RelayWebSocket