# kingsplaybook-mcp

The official [MCP](https://modelcontextprotocol.io) server for the
**KingsPlaybook Developer API**. It gives an AI agent — one building a
sports-betting bot, a model, or an analytics tool — direct access to
KingsPlaybook's data as native tools:

- **Confirmed lineups** — NBA, MLB, NHL
- **Player projections** — the projection engine's raw output
- **Canonical game lines** — moneyline / spread / total, aggregated across books
- **Pick-history archive** — the publicly-posted record, with results + closing lines

It's a thin local (stdio) wrapper over the [`/v1` REST API](https://kingsplaybook.org/devs).
Same data, second protocol.

## Get an API key

Sign up at **[kingsplaybook.org/devs](https://kingsplaybook.org/devs)**. The
Free tier covers lineups; paid tiers add projections, lines, and history.
Your key looks like `kp_live_…`.

## Install

No install step — run it straight from npm with `npx`. Add it to your MCP
client config (Claude Desktop, Cursor, etc.):

```json
{
  "mcpServers": {
    "kingsplaybook": {
      "command": "npx",
      "args": ["-y", "kingsplaybook-mcp"],
      "env": {
        "KINGSPLAYBOOK_API_KEY": "kp_live_your_key_here"
      }
    }
  }
}
```

That's it — the agent now has the KingsPlaybook tools.

## Tools

| Tool | What it returns | Min. plan |
|------|-----------------|-----------|
| `kingsplaybook_get_lineups` | Confirmed lineups for a league + date | Free |
| `kingsplaybook_get_projections` | Raw player projections for a league + date | Starter |
| `kingsplaybook_get_lines` | Canonical game lines for a league + date | Pro |
| `kingsplaybook_get_pick_history` | Posted picks + results for a date | Premium |
| `kingsplaybook_get_freshness` | Per-domain data-age signal | Free |

Every tool returns JSON. Calling a tool above your plan tier returns a
clear `403` message with an upgrade link.

### Examples

- *"What's tonight's NBA slate look like?"* → `kingsplaybook_get_lineups({ league: "nba", date: "2026-05-21" })`
- *"Pull MLB projections for today"* → `kingsplaybook_get_projections({ league: "mlb", date: "2026-05-21" })`
- *"How did KingsPlaybook's prop picks do yesterday?"* → `kingsplaybook_get_pick_history({ date: "2026-05-20", type: "prop" })`

## Configuration

| Env var | Required | Default | Purpose |
|---------|----------|---------|---------|
| `KINGSPLAYBOOK_API_KEY` | yes | — | Your `kp_live_` API key |
| `KINGSPLAYBOOK_API_URL` | no | `https://api.kingsplaybook.org` | Override the API base URL |

## Local development

```bash
npm install
npm run build      # compile TypeScript to dist/
npm start          # run the built server (needs KINGSPLAYBOOK_API_KEY)
npm run dev        # watch mode
```

## Links

- [Developer API & plans](https://kingsplaybook.org/devs)
- [Model Context Protocol](https://modelcontextprotocol.io)

## License

MIT