Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/serginator/arkhamdb-mcp

ArkhamDB MCP server to be able to get information from decks and analyze synergies
https://github.com/serginator/arkhamdb-mcp

Last synced: 8 days ago
JSON representation

ArkhamDB MCP server to be able to get information from decks and analyze synergies

Awesome Lists containing this project

README 

          
# 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



### Performance

- **24h in-memory cache** for cards and packs — expensive API calls made at most once per day



## 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](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](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](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](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](examples/darrell-english.md)



## Installation



1. Clone this repository

2. Install dependencies:



```bash

make dependencies

```



Or manually:



```bash

go mod download

```



3. Build the server:



```bash

make build

```



Or manually:



```bash

go build -o arkhamdb-mcp

```



## Running with Docker



1. Build and start the server:



```bash

docker-compose up --build

```



2. The server will listen on stdin/stdout using the MCP protocol.



For Cursor integration, you can use the `run-docker-mcp.sh` script:



```json

{

  "mcpServers": {

    "arkhamdb": {

      "command": "/arkhamdb-mcp/run-docker-mcp.sh",

      "args": []

    }

  }

}

```



## Usage



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:



```bash

./test-mcp.sh

```



Or test manually using JSON-RPC over stdin:



#### Initialize the server:



```bash

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:



```bash

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:



```bash

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:



```bash

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:



```bash

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:



```bash

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:



```bash

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



Configure your AI client to connect to this server using the MCP protocol over stdio. For Cursor, add to your `mcp.json`:



```json

{

  "mcpServers": {

    "arkhamdb": {

      "command": "/arkhamdb-mcp/arkhamdb-mcp",

      "args": []

    }

  }

}

```



## API Reference



The server uses the public ArkhamDB API endpoints:



- `GET /api/public/card/{card_code}.json` - Get a single card

- `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](https://es.arkhamdb.com/api/doc).



## 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 cards and packs

  - `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