All Documentation

Connect Grimoire to Claude with MCP

Connect your campaign to Claude with a single click. No Node.js, no config files, no API tokens to copy. Ask about your world in plain English.

Grimoire is an MCP server, which means you can plug it into Claude (claude.ai or the Claude Desktop app) and ask questions about your campaign in plain English. Claude fetches NPCs, locations, factions, wiki pages, open story threads, and anything else it needs directly from your campaign.

No installation. No copy-pasting tokens. No JSON config files. You add Grimoire to Claude once, sign in with your existing Grimoire account, choose a campaign, and you are connected.

What Claude can do once connected

  • Read everything about the single campaign you picked: NPCs, locations, factions, items, lore, quests, sessions, relationships, the campaign bible, the wiki, and open story threads.
  • Create and update on your behalf if you are the Gamemaster ("Create an NPC named Thrain, a dwarven weaponsmith based in Millbrook").
  • Respect visibility rules. GM Secret content stays GM-only. Player connections cannot read secrets or modify anything.
  • Stay within one campaign. A connection is bound to the campaign you approved on the consent screen. Claude cannot see your other campaigns through the same connection.

How to connect (Claude.ai web)

Step 1: Open Claude's Connector settings

Sign in to claude.ai, open Settings (your profile icon → Settings), then choose Connectors in the sidebar.

Step 2: Add a custom connector

Scroll to the bottom and click Add custom connector. A dialog asks for a server URL. Paste:

https://api.ttrpg.bot/mcp

Click Add.

Step 3: Sign in to Grimoire

Claude opens a Grimoire login page in a new tab. Sign in with the same account you use for the Grimoire app: Google, Discord, or your email and password.

Step 4: Choose a campaign

After login, Grimoire shows a consent screen with your campaigns. Campaigns you run are listed under Your campaigns; campaigns you play in appear under Campaigns you play in when their GM has enabled player access (see below). Pick one, review the permissions, and click Approve & connect.

Step 5: Use it

Back in Claude.ai, the Grimoire connector appears under the paperclip menu and Claude uses it whenever a question needs campaign data. Try:

"What NPCs are in my campaign?"

"Who is the blacksmith in Millbrook, and what's their relationship to the Merchant's Guild?"

"Create an NPC named Thrain, a dwarven weaponsmith, blunt but fair, sells custom armor."

"Summarize our last session and what story threads are still open."

"Help me prep next week's session: what factions are scheming, and which NPCs are likely to show up?"

How to connect (Claude Desktop)

The flow is the same. Open Claude Desktop, go to Settings → Connectors → Add custom connector, paste https://api.ttrpg.bot/mcp, sign in, pick a campaign, approve. Claude Desktop opens the consent flow in your default browser.

Player access: let your table bring an AI too

Your players can connect their own Claude to the campaign, but only if you allow it, and only ever read-only:

  1. As the GM, open Knowledge → MCP & AI → Player access and turn the toggle on. It is off by default.
  2. Optionally write a short guidance note for your players' AI assistants (house expectations, spoiler etiquette). It is guidance, not a lock; the hard limits below are enforced by the server regardless.
  3. Players then add the same connector URL, and your campaign appears under Campaigns you play in on their consent screen.

What a player connection can never do, no matter what the AI asks for:

  • Read anything marked GM Secret, session prep, or another player's wiki
  • See more of the world than the portal preset reveals
  • Create, edit, or delete anything

Turning the toggle off, or removing the player from the campaign, cuts their AI access immediately, not when a token happens to expire. Every AI call, yours and theirs, lands in the activity log under Knowledge → MCP & AI → Audit Log, labeled by who made it.

Switching campaigns

A connection is bound to a single campaign so Claude only sees what you explicitly granted. To point Claude at a different campaign, remove the connector and add it again, picking the new campaign on the consent screen. You can also keep two connections side by side (add the URL twice, pick a different campaign each time).

Revoking access

  1. From Claude: remove the Grimoire connector from Settings → Connectors.
  2. From Grimoire: revoke any client's access in your account settings; active tokens expire within 15 minutes.
  3. Account-wide: email [email protected] if you think a token leaked and we revoke everything tied to your account.

What Claude actually sees

When you grant access, Claude does not download a copy of your campaign. It calls Grimoire each time it needs something; the data lives on Grimoire's servers, and Claude sees only the specific entity, page, or search result it asked for in the moment. More in our Privacy Policy.

Tool inventory

The MCP server currently exposes 48 tools (the number grows as features ship). A representative selection:

Search & read (read-only): search_campaign · get_entity · list_entities · get_entity_catalog · get_campaign_bible · get_wiki_page · get_wiki_tree · get_relationships · get_knowledge_graph · get_open_threads · get_narrative_state · current_campaign

Create & modify (Gamemaster connections only): create_entity · update_entity · delete_entity · batch_create_entities · update_campaign_bible · create_wiki_page · create_wiki_block · add_relationship · create_open_thread · resolve_open_thread · add_thread_progression

Claude decides which tool to call based on your question; you never need this list.

Troubleshooting

"I don't see a Connect button after adding the URL."

Make sure you pasted exactly https://api.ttrpg.bot/mcp with no trailing slash or query string. The connector should appear under Settings → Connectors with a Sign in button next to it.

"The consent screen shows no campaigns."

For Your campaigns: the account you signed in with does not run any campaigns yet. For Campaigns you play in: the GM has not enabled Player access for that campaign; ask them to flip it on under Knowledge → MCP & AI.

"Claude says it doesn't know about something I know is in the campaign."

Three common causes: the connector's tools are toggled off in Claude's tool permissions; the content is GM Secret and you are connected as a player; or (for players) the portal preset simply has not revealed it yet.

"Connection expired" / Claude asks me to reconnect.

Tokens are short-lived and refresh automatically. If a refresh fails, click reconnect and approve again. For players: if reconnecting fails outright, your GM may have turned Player access off.