TDC MCP Server
An MCP server that exposes True Dungeon Companion game data — tokens, set/group bonuses, and rulebook pages — as tools for Claude and other MCP clients.
Tools
| Tool | Description |
|---|---|
search_tokens | Search tokens by name, slot, rarity, or class |
advanced_search_tokens | Build arbitrary AND/OR filter trees across 29 fields (abilities, stats, damage, etc.) |
get_token | Get full detail for a single token (effects, slots, damage wheel, etc.) |
list_set_bonuses | List all set bonuses with tier effects |
get_set_bonus | Get a single set bonus by id |
list_group_bonuses | List all group bonuses with tier effects |
get_group_bonus | Get a single group bonus by id |
list_rulebook_pages | List all rulebook pages (title + path) |
get_rulebook_page | Get the full text content of a rulebook page |
get_api_version | Get the running TDC API build version and start time |
Quick start (npx)
No install or build needed. Add to your .claude/settings.json:
{
"mcpServers": {
"tdc": {
"command": "npx",
"args": ["@tdcompanion/mcp-server"],
"env": {
"TDC_API_KEY": "tdc_live_<your-key>"
}
}
}
}
Environment variables
| Variable | Default | Description |
|---|---|---|
TDC_API_BASE_URL | https://api.tdcompanion.app | API base URL (must point at the API host, not the web app) |
TDC_API_KEY | (none) | Optional bearer key for higher rate limits (600 req/min vs 60) |
The server works without an API key (anonymous access), but authenticated keys get 10x the rate limit. Generate one from your profile's Developer tab at https://tdcompanion.app/profile.
Development
cd src/MCP/@tdcompanion/mcp-server
npm install
npm run build # compile TypeScript → dist/
npm start # run locally via stdio
Publishing
npm run build
npm publish
The prepublishOnly script runs the build automatically. The files field in package.json ensures only dist/ is included in the published package.
Changelog
1.1.0
- Added
get_set_bonus,get_group_bonus, andget_api_versiontools. - Stricter input validation: pagination is clamped (
skip >= 0,take1–200), andslot/rarity/classreject unknown values up front. advanced_search_tokensvalidates thefilterJSON is a FilterExpression object before sending.- All tools return a clean
{ isError: true }result on failure instead of throwing. - Rulebook HTML stripping now handles numeric entities (
&#x…;,&#…;) and preserves list structure. - List-style tools truncate output over ~20k chars with a clear "…N more truncated" footer.