# EDHREC MCP Server

A local MCP server that gives Claude access to EDHREC's Commander deckbuilding data — recommended cards, synergies, combos, and average decklists.

EDHREC has no official public API. This server calls the same JSON endpoints (`json.edhrec.com`) that edhrec.com's own frontend uses to render its pages. These endpoints are **undocumented and unofficial** — they may change or break without notice. No API key is needed.

## Tools

- `edhrec_get_commander_recommendations` — card recommendations for a commander, grouped by category (High Synergy, Top Cards, Creatures, etc.)
- `edhrec_get_card_synergies` — cards that synergize with a given (often non-commander) card, plus known combos
- `edhrec_get_average_decklist` — EDHREC's precomputed average 100-card decklist for a commander

## Setup

### 1. Install dependencies

Requires Python 3.10+.

```
cd "edhrec_mcp"
pip install -r requirements.txt
```

### 2. Test it directly (optional)

```
python server.py
```

With no `PORT` environment variable set, this runs over stdio (for the MCP Inspector or a classic Claude Desktop config). You can also exercise it with the MCP Inspector:

```
npx @modelcontextprotocol/inspector python server.py
```

### 3. Register it as a connector in Cowork (this project)

Cowork's "Add custom connector" dialog only accepts a remote MCP server URL — it can't point at a local script. `server.py` runs over streamable-HTTP automatically whenever a `PORT` environment variable is present (which is how Render and most PaaS hosts tell an app what to bind to). That's what makes it deployable.

Deploy to Render (free tier):

1. Push the contents of this `edhrec-mcp` folder to a new GitHub repo (the folder's contents should be the repo root — `server.py`, `requirements.txt`, and `render.yaml` at the top level).
   ```
   cd "edhrec-mcp"
   git init
   git add .
   git commit -m "EDHREC MCP server"
   git branch -M main
   git remote add origin https://github.com/<your-username>/edhrec-mcp.git
   git push -u origin main
   ```
2. Go to render.com → sign in with GitHub → New → Blueprint → select your `edhrec-mcp` repo. Render will read `render.yaml` and configure the service automatically. Click Apply.
3. Wait for the first deploy to finish (a few minutes). Render gives you a URL like `https://edhrec-mcp.onrender.com`.
4. Sanity-check it's alive by visiting `https://edhrec-mcp.onrender.com/mcp` in a browser — a 4xx/JSON error about missing headers is fine; that means the MCP endpoint is up.
5. In Cowork, open Settings → Connectors → Add custom connector, and paste:
   - Name: EDHREC (or anything you like)
   - Remote MCP server URL: `https://edhrec-mcp.onrender.com/mcp`
   - Leave Advanced settings (OAuth) blank — this server has no auth.
6. Save. The EDHREC tools should now show up as a connector you can enable in any conversation.

Note on the free tier: Render's free web services spin down after ~15 minutes of inactivity and take 30-60 seconds to wake back up on the next request (cold start).

## Notes

- Card/commander names are converted to EDHREC's URL slug format internally (lowercase, punctuation stripped, spaces to hyphens). If a lookup fails, double-check the exact card name spelling — fuzzy matching isn't available the way Scryfall offers it.
- These endpoints are unofficial; please use them at a reasonable, interactive-use request rate.