// CHOOSE_YOUR_PATH

Two ways to play Quest Keeper AI:

  • Desktop App - Full Tauri application with 3D battlemap, character sheets, and built-in chat
  • MCP Backend - Use with Claude Desktop, RooCode, KiloCode, or any MCP client

🖥️ Quest Keeper AI Desktop App

The complete experience with visual interface, 3D battlemap, and multi-LLM support.

Best for: Solo play, visual feedback, integrated experience

Setup Desktop App →

⚙️ rpg-mcp Backend Only

Use the MCP server with your preferred AI client for text-based adventures.

Best for: Existing MCP workflows, Claude Desktop users, developers

Setup MCP Backend →

// DESKTOP_APP_SETUP

Prerequisites

1 Clone the Repositories

# Clone the frontend git clone https://github.com/Mnehmos/QuestKeeperAI-v2.git cd QuestKeeperAI-v2 git clone https://github.com/Mnehmos/rpg-mcp.git

2 Build the Unified Server

cd rpg-mcp npm install npm run build:binaries

📦 Output: This creates platform-specific binaries in bin/:

  • dnd-mcp-server-win.exe (Windows)
  • dnd-mcp-server-macos (macOS)
  • dnd-mcp-server-linux (Linux)

3 Copy Binary to Frontend

# Windows example copy bin\dnd-mcp-server-win.exe ..\QuestKeeperAI-v2\src-tauri\binaries\dnd-mcp-server-x86_64-pc-windows-msvc.exe # macOS example cp bin/dnd-mcp-server-macos ../QuestKeeperAI-v2/src-tauri/binaries/dnd-mcp-server-x86_64-apple-darwin # Linux example cp bin/dnd-mcp-server-linux ../QuestKeeperAI-v2/src-tauri/binaries/dnd-mcp-server-x86_64-unknown-linux-gnu

4 Install & Run Frontend

cd ../QuestKeeperAI-v2 npm install npm run tauri dev

5 Configure API Keys

Click the ⚙️ Settings button in the app and add your LLM API key(s).

🎮 You're ready! Start chatting with the AI to create characters and begin your adventure.

// MCP_BACKEND_ONLY

Use rpg-mcp with any MCP-compatible client:

🤖 Claude Desktop

Official Anthropic desktop app with native MCP support

Download Claude Desktop →

🦘 KiloCode

AI-powered VS Code extension with MCP support

Visit KiloCode →

🦙 RooCode

Full-featured AI development environment

Visit RooCode →

1 Clone & Build

git clone https://github.com/Mnehmos/rpg-mcp.git cd rpg-mcp npm install npm run build

2 Configure MCP Client

Add to your MCP settings file:

Config location:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{ "mcpServers": { "rpg-mcp": { "command": "node", "args": ["PATH_TO_REPO/rpg-mcp/dist/index.js"], "env": {} } } }

Config location: %APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json

{ "mcpServers": { "rpg-mcp": { "command": "node", "args": ["PATH_TO_REPO/rpg-mcp/dist/index.js"], "cwd": "PATH_TO_REPO/rpg-mcp", "enabled": true, "alwaysAllow": ["*"] } } }

⚠️ Important: Replace PATH_TO_REPO with the actual path to your cloned repository!

3 Restart & Play

Restart your MCP client and start playing!

// CONFIGURATION

Database Location

rpg-mcp uses SQLite for persistence. The database (rpg.db) is created in the working directory.

Pre-populated Content

The bundled database includes Fellowship of the Ring content ready to play:

  • 9 Fellowship characters with full stats
  • Signature items (Sting, Glamdring, etc.)
  • Starting quests and locations

Environment Variables

# Optional: Custom database path DATABASE_PATH=./data/custom.db # Optional: Debug logging DEBUG=rpg-mcp:*

// YOUR_FIRST_GAME

Test the Connection

In the desktop app, type /test to list all available MCP tools.

Example Commands

  • "List all characters" - See pre-loaded Fellowship
  • "Create a level 3 dwarf fighter named Thorin" - New character
  • "Give Thorin a battleaxe" - Add items
  • "Start combat with 3 goblins" - Begin encounter
  • "Roll 2d6+3 for damage" - Dice rolling
  • "Create a quest to find the lost ring" - Quest system

Available Tool Categories

  • CRUD: create_character, get_character, list_characters, update_character, delete_character
  • Inventory: create_item_template, give_item, remove_item, equip_item, get_inventory
  • Combat: create_encounter, execute_combat_action, advance_turn, end_encounter
  • Quests: create_quest, assign_quest, update_objective, complete_quest, get_quest_log
  • World: generate_world, get_world_state, apply_map_patch
  • Math: dice_roll, probability_calculate
  • Secrets: create_secret, reveal_secret, check_reveal_conditions
  • Strategy: create_nation, propose_alliance, resolve_turn

// TROUBLESHOOTING

MCP Server Not Starting

  • Check that Node.js 18+ is installed: node --version
  • Ensure the path in your MCP config is correct
  • Try running node dist/index.js directly to see errors

Desktop App Build Errors

  • Ensure Rust is installed: rustc --version
  • Run npm run tauri info to check dependencies
  • On Windows, install Visual Studio Build Tools

Database Issues

  • Delete rpg.db to reset to clean state
  • Check file permissions in the working directory
  • Ensure only one instance is running (SQLite locking)

Need Help?