All Documentation

Claude Desktop MCP Setup

Connect Claude Desktop to Grimoire via MCP.

Grimoire includes a built-in MCP (Model Context Protocol) server that allows AI assistants like Claude to query and manage your campaign data.

What is MCP?

MCP is a protocol that allows AI assistants to interact with external tools and data sources. With Grimoire's MCP server, Claude can:

  • Query NPCs, locations, factions, and other entries
  • Create and update campaign content
  • Search across your entire campaign
  • Understand relationships between entities

Prerequisites

  • Node.js 18 or higher - Required to run the MCP bridge. Download from nodejs.org
  • Grimoire account (any tier)
  • Claude Desktop application - Download from claude.ai

Setup Instructions

Step 1: Install mcp-remote

Open a terminal (Command Prompt, PowerShell, or Terminal) and install the MCP remote bridge:

npm install -g mcp-remote

Step 2: Get Your MCP Token

  1. Log in to Grimoire
  2. Open your campaign
  3. Go to Campaign Settings (gear icon) > MCP Configuration
  4. Click Create Token
  5. Copy the token and note your Campaign ID

Step 3: Open Claude Desktop Config

  1. Open Claude Desktop
  2. Click the Settings icon (gear)
  3. Go to Developer settings
  4. Click "Edit Config" to open your claude_desktop_config.json file

Step 4: Add Grimoire Configuration

Add this to your config file (replace YOUR_CAMPAIGN_ID and YOUR_TOKEN):

{
  "mcpServers": {
    "grimoire": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://api.ttrpg.bot/api/v1/mcp/YOUR_CAMPAIGN_ID/sse",
        "--header",
        "Authorization: Bearer YOUR_TOKEN"
      ]
    }
  }
}

Step 5: Restart Claude Desktop

Close and reopen Claude Desktop to load the new configuration.

Step 6: Verify Connection

In Claude Desktop, you should see "Grimoire" in the available tools (look for the hammer icon). Try asking:

"What NPCs are in my campaign?"

Available Tools

The MCP server provides these tools:

Query Tools

  • search_campaign - Search across all entity types
  • get_entity - Get full details of a specific entity
  • list_entities - List entities by category

Knowledge Tools

  • get_constitution - Get world foundations and campaign bible
  • get_knowledge_graph - Get relationship graphs
  • get_wiki_tree - Get wiki page structure

Modification Tools (GM only)

  • create_entity - Create a new entity
  • update_entity - Update an existing entity
  • delete_entity - Remove an entity
  • add_relationship - Link entities together

Wiki Tools

  • get_wiki_page - Get wiki page content
  • create_wiki_page - Create wiki pages
  • create_wiki_block - Add content blocks

Example Prompts

Here are some things you can ask Claude:

  • "Who is the blacksmith in Millbrook?"
  • "What factions are allied with the Merchant's Guild?"
  • "Create an NPC named Thrain, a dwarven weaponsmith"
  • "What happened in our last session?"
  • "Help me prep for the next session"

Troubleshooting

"Command not found: npx"

  • Make sure Node.js is installed: node --version
  • If not installed, download from nodejs.org

"Connection failed"

  • Check your MCP token is correct and not expired
  • Ensure the campaign ID exists
  • Verify you're connected to the internet

"Permission denied"

  • Some tools require GM role
  • Player tokens have read-only access

Claude doesn't see the tools

  • Restart Claude Desktop completely
  • Verify your JSON config is valid (no trailing commas)
  • Check for error messages in Claude Desktop

Security Notes

  • Your MCP token has access to your campaign data
  • Never share your token publicly
  • Regenerate tokens if compromised
  • AI queries respect visibility settings - DM secrets stay secret
Quickstart Guide Entity Types