MCP ArkhamDB Server

An MCP (Model Context Protocol) server for interacting with the ArkhamDB public API. This server provides tools to query cards and decks from Arkham Horror: The Card Game.

Features

Card Lookup

• Get Card: Retrieve details of a specific card by its code
• Search Cards by Name: Search for cards by name (case-insensitive partial match)
• Search Cards Advanced: Filter cards by chapter (1=legacy, 2=2026 relaunch), cycle, faction, type, XP range, cost range, traits, and tags

Packs & Campaigns

• Get Packs and Cycles: List all packs grouped by cycle with chapter and availability information

Deck Analysis

• Get Deck: Retrieve a deck by its ID
• Get Decklist: Retrieve a decklist by its ID
• Find Card Synergies: Discover cards that synergize with a given card based on text analysis, trait matching, and mechanic keywords
• Suggest Deck Improvements: Suggest cards that would improve an existing deck, respecting investigator restrictions

AI Deck Building

• Get Investigator Constraints: Full deck-building rules for an investigator — deck size, required signatures, random weaknesses, and all deck_options (faction/level/trait/tag/limit restrictions)
• Build Starter Deck: Build a complete legal deck for an investigator with chapter, campaign cycle, and XP budget awareness
• Search Reference Decks: Search recently published community decklists filtered by investigator, XP spent, and tags
• Get Upgrade Path: Suggest XP spending plan for upgrading an existing deck — upgrades scored by synergy
• Validate Deck: Full legality check — deck size, required signatures, deck_options compliance, card limits

Collection & Preferences

• Get Collection: Retrieve your saved collection config (owned cycles, language preference, taboo setting)
• Set Collection: Save which cycles/packs you own, your language preference (es or en), and whether to enforce the taboo list — persisted to ~/.arkhamdb-collection.json
• Adapt Deck to Collection: Take a public decklist, flag cards you don't own, and suggest owned replacements of the same faction/type/XP level

Localization

• All tools that surface card names (search, synergies, deck building, validation, upgrades) honor the language set via Set Collection: "es" returns the localized Spanish name, "en" (default) returns the English name.
• Names are resolved per card from ArkhamDB's single-card endpoint when the bulk card listing hasn't caught up with a translation yet (common right after a new pack releases), so freshly released content still gets correct Spanish names.

Performance

• 24h in-memory cache for cards and packs — expensive bulk API calls made at most once per day
• 24h in-memory per-card cache backing the localization fallback above, so repeated lookups for the same card don't re-hit the API

Example of promts using the MCP server

In Spanish

Utiliza el mcp de arkhamdb para bajar información sobre el siguiente mazo: 5570650

Quiero que analices todas sus cartas, sus sinergias, y me expliques sus puntos fuertes y sus debilidades, y cómo utilizarlo y jugar este mazo, incluyendo información sobre qué mulligan debería hacer. Puedes buscar en internet información sobre Arkham Horror LCG. Los nombres de las cartas y la explicación han de estar en español.

Result: examples/darrell-spanish.md

Sugiéreme mejoras para este mazo 5570650 usando el mcp de arkhamdb, recuerda poner los nombres de las cartas en español, recuerda que el mazo no puede tener más de 30 cartas (sin contar las propias de darrell), por lo que no se puede añadir cartas y ya está, hay que quitar otras. Hay muchas más cartas en el mazo, intenta enfocarte en cartas que aprovechen sinergias con "evidence", con añadir pruebas y usar pruebas con la habilidad de darrell, y también con cartas para descubrir más pistas

Result: examples/darrell-mejoras.md

Usa el MCP de arkhamdb para encontrar sinergias para Darrell Simmons, que usa `evidence`, recuerda usar el nombre español de las cartas

Result: examples/darrell-sinergias.md

Ayúdame a montar un mazo de Trish Scarborough para jugar la campaña de Innsmouth. Puedes buscar información sobre mazos en internet y usar las herramientas del MCP de arkhamdb. He visto dos posibles mazos iniciales, aunque no me gusta lo de empezar con "En la brecha". https://es.arkhamdb.com/deck/view/2635733 https://es.arkhamdb.com/decklist/view/26638/trish-scarborough-starter-deck-1.0

Result (after some iterations): examples/trish-scarborough-deck.md

In English

Use the arkhamdb mcp to get information about the following deck: 5570650

I want you to analyze all its cards, its synergies, and explain its strengths and weaknesses, and how to use it and play this deck, including information about what mulligan should be made. You can search the internet for information about Arkham Horror LCG.

Result: examples/darrell-english.md

Installation

1. Clone this repository
2. Install dependencies:

make dependencies

Or manually:

go mod download

1. Build the server:

make build

Or manually:

go build -o arkhamdb-mcp main.go

Usage with MCP Clients (Recommended)

The easiest way to use this server is to configure it directly in your MCP client configuration file (e.g., mcp.json for Cursor or Claude Desktop).

Add the following to your mcp.json:

{
  "mcpServers": {
    "arkhamdb": {
      "command": "/absolute/path/to/arkhamdb-mcp/arkhamdb-mcp",
      "args": []
    }
  }
}

Replace /absolute/path/to/arkhamdb-mcp/arkhamdb-mcp with the full path to the binary in this repository.

The server will start automatically when your AI client needs it and communicate via stdin/stdout using the MCP protocol.

Running with Docker (Alternative)

If you prefer to use Docker instead of the native binary:

1. Build the Docker image:

make build-docker

1. For MCP client integration with Docker, use the run-docker-mcp.sh script:

{
  "mcpServers": {
    "arkhamdb": {
      "command": "/absolute/path/to/arkhamdb-mcp/run-docker-mcp.sh",
      "args": []
    }
  }
}

How It Works

The server communicates via stdin/stdout using the MCP protocol. It connects to the ArkhamDB API at https://es.arkhamdb.com.

Testing

Use the provided test script:

./test-mcp.sh

Or test manually using JSON-RPC over stdin:

Initialize the server:

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}' | ./arkhamdb-mcp

List available tools:

echo -e '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | ./arkhamdb-mcp

Get a card:

echo -e '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"arkhamdb_get_card","arguments":{"cardCode":"01001"}}}' | ./arkhamdb-mcp

Search cards by name:

echo -e '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"arkhamdb_search_cards_by_name","arguments":{"name":"Roland"}}}' | ./arkhamdb-mcp

Get a deck:

echo -e '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"arkhamdb_get_deck","arguments":{"deckID":12345}}}' | ./arkhamdb-mcp

Find card synergies:

echo -e '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"arkhamdb_find_card_synergies","arguments":{"cardCode":"06332","maxResults":10}}}' | ./arkhamdb-mcp

The synergy finder analyzes cards using multiple methods:

• Trait References: Finds cards that match explicit trait references (e.g., [[Item]], [[Spell]])
• Shared Traits: Identifies cards with matching traits
• Mechanic Keywords: Detects cards that interact with similar game mechanics (investigation, damage, resources, etc.)
• Slot Compatibility: Considers equipment slot compatibility

Suggest deck improvements:

echo -e '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test-client","version":"1.0.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"arkhamdb_suggest_deck_improvements","arguments":{"decklistID":5570650,"maxResults":20}}}' | ./arkhamdb-mcp

The deck improvement tool analyzes a deck and suggests cards that would improve it:

• Investigator Requirements: Respects deck size, class restrictions (faction), level limits, and experience requirements
• Synergy Analysis: Scores cards based on synergies with existing deck cards
• Deck Compatibility: Only suggests cards that are legal for the investigator
• Prioritization: Favors low-cost and level 0 cards for easier inclusion

Integration with AI Models

This MCP server can be integrated with:

• Cursor
• Claude Desktop
• ChatGPT with MCP support
• Any MCP-compatible AI client

See the Usage with MCP Clients section above for configuration instructions.

API Reference

The server uses the public ArkhamDB API endpoints:

• GET /api/public/card/{card_code}.json - Get a single card (also used as a per-card fallback to refresh stale/untranslated names from the bulk listing)
• GET /api/public/cards/ - Get all cards (cached 24h)
• GET /api/public/packs/ - Get all packs (cached 24h)
• GET /api/public/deck/{deck_id}.json - Get a deck (may require authentication)
• GET /api/public/decklist/{decklist_id}.json - Get a decklist
• GET /api/public/decklists/by_date/{date}.json - Get community decklists for a date (used by search reference decks)

For more information, see the ArkhamDB API documentation.

Development

Code Quality

• Lint: Run make lint to check code quality
• Format: Run make format to format code
• Inspect: Run make inspect to inspect MCP protocol compliance

Makefile Targets

• make dependencies - Install all dependencies
• make lint - Run linter
• make format - Format code
• make inspect - Inspect MCP protocol compliance
• make build - Build Docker image

Architecture

The server follows a modular architecture:

• main.go - Entry point and initialization
• server/ - MCP protocol implementation and tool dispatch
• tools/ - Tool interface definitions
• arkhamdb/ - ArkhamDB API client implementation
  • arkhamdb.go - API client, card/deck fetching, SearchCardsAdvanced, GetInvestigatorConstraints, GetUpgradePath
  • cache.go - 24h in-memory cache for bulk cards/packs plus a per-card cache used for name localization fallback
  • collection.go - Collection config (owned cycles, language, taboo) load/save to ~/.arkhamdb-collection.json
  • deck_options.go - deck_options / deck_requirements JSON parsing and card legality checking
  • packs.go - Pack fetching, cycle grouping, GetPacksAndCycles
  • builder.go - BuildStarterDeck and helpers (pack filtering, option limit tracking)
  • reference_decks.go - SearchReferenceDecks (date-iteration over community decklists)
  • validator.go - ValidateDeck (full legality check)
  • synergy.go - Synergy detection logic (text parsing, trait matching, scoring)

License

MIT License