# Odds API MCP server for your AI assistant

Official MCP server

Connect Claude, Codex, Cursor or VS Code to live and historical odds from 450+ bookmakers. Ask for prices, line movement, value bets or bet results in plain words, or let your assistant write the code.

Free and open source · 25 tools · npm, Docker and one-click Claude Desktop install

[Get an API key](https://odds-api.io/pricing) · [npm](https://www.npmjs.com/package/odds-api-mcp-server) · [GitHub](https://github.com/odds-api-io/odds-api-mcp-server) · [Docker Hub](https://hub.docker.com/r/oddsapi/odds-api-mcp-server)

## Connected in under a minute

1. **Get an API key**: Pick a plan and choose your bookmakers. Your key is on the dashboard as soon as the payment goes through.
2. **Add the server to your AI tool**: Paste one command or one JSON block. The server runs on your own machine with npx or Docker and reads the key from an environment variable.
3. **Ask in plain words**: Your assistant picks the right tools, calls the API and answers with live prices. It can also write and test code against the same data.

**Claude Code** (Run in your terminal)

```bash
claude mcp add odds-api \
  --env ODDS_API_KEY="your-api-key" \
  -- npx -y odds-api-mcp-server
```

**Codex** (Run in your terminal)

```bash
codex mcp add odds-api \
  --env ODDS_API_KEY="your-api-key" \
  -- npx -y odds-api-mcp-server
```

**Claude Desktop** (Add to claude_desktop_config.json)

```json
{
  "mcpServers": {
    "odds-api": {
      "command": "npx",
      "args": [
        "-y",
        "odds-api-mcp-server"
      ],
      "env": {
        "ODDS_API_KEY": "your-api-key"
      }
    }
  }
}
```

**Cursor** (Add to .cursor/mcp.json)

```json
{
  "mcpServers": {
    "odds-api": {
      "command": "npx",
      "args": [
        "-y",
        "odds-api-mcp-server"
      ],
      "env": {
        "ODDS_API_KEY": "your-api-key"
      }
    }
  }
}
```

**VS Code** (Add to .vscode/mcp.json)

```json
{
  "servers": {
    "odds-api": {
      "command": "npx",
      "args": [
        "-y",
        "odds-api-mcp-server"
      ],
      "env": {
        "ODDS_API_KEY": "your-api-key"
      }
    }
  }
}
```

**Docker** (Any MCP client, no Node.js needed)

```json
{
  "mcpServers": {
    "odds-api": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "ODDS_API_KEY",
        "oddsapi/odds-api-mcp-server"
      ],
      "env": {
        "ODDS_API_KEY": "your-api-key"
      }
    }
  }
}
```

Using Claude Desktop? Download the [.mcpb file](https://github.com/odds-api-io/odds-api-mcp-server/releases/latest) from the latest release and open it. Claude asks for your key and does the rest.

## What you can ask

Real questions, answered from live data. Under each one are the tools the assistant calls to answer it.

- Which Premier League matches this weekend have the biggest gap between Bet365 and Unibet on the match result? (`get_events`, `get_multi_odds`)
- How has the Over 2.5 goals price on Arsenal v Chelsea moved at Bet365 since yesterday? (`search_events`, `get_odds_movements`)
- Which NBA odds are dropping fastest tonight? (`get_dropping_odds`)
- List the value bets at Betano right now, sorted by expected value. (`get_value_bets`)
- I backed Liverpool -1 Asian handicap and Over 2.5 goals in their Premier League match yesterday. Did the bets win? (`get_historical_events`, `grade_bets`)
- Write a Python script that sends a Telegram message when an arbitrage above 2% shows up between my bookmakers. (`get_documentation`, `get_arbitrage_bets`)

## 25 tools, the whole API

The tools cover the whole v3 API, so anything your assistant finds in chat works the same way in your code.

### Odds

- `get_odds`: All markets for one event from up to 30 bookmakers
- `get_multi_odds`: Odds for up to 10 events in one call
- `get_updated_odds`: Only the odds that changed since a timestamp
- `get_odds_movements`: Price history for one line at one bookmaker
- `get_dropping_odds`: Lines that dropped most since opening, by sport and league

### Events

- `get_events`: Fixtures by sport, league, team, date or status
- `get_event`: One event by id
- `get_live_events`: Every event in play right now
- `search_events`: Find an event by team name

### Betting tools

- `get_value_bets`: Positive expected value prices at a bookmaker
- `get_arbitrage_bets`: Arbitrage opportunities across your bookmakers

### History and settlement

- `get_historical_events`: Finished events by sport, league and date
- `get_historical_odds`: Closing odds and the final score of a finished event
- `get_settlements`: Status and final score by period for up to 50 events
- `grade_bets`: Settle up to 50 bets as won, lost, void or half

### Reference

- `get_sports`: Every sport and its slug
- `get_leagues`: Leagues for a sport with event counts
- `get_markets`: Exact market names per sport, pre-match and live
- `get_bookmakers`: Every bookmaker and whether it is active
- `get_participants`: Teams and players for a sport
- `get_participant`: One team or player by id

### Your account and docs

- `get_selected_bookmakers`: The bookmakers on your plan
- `select_bookmakers`: Add bookmakers to your selection
- `clear_selected_bookmakers`: Reset your selection, once every 12 hours
- `get_documentation`: The full API docs, so code works on the first run

## Runs on your machine, reads the live API

### Your key stays on your machine

The server runs locally over stdio and talks straight to api.odds-api.io. Nothing sits in between, and the key lives in your MCP config.

### Same data as the API

450+ bookmakers, 34 sports, pre-match and live, in one JSON schema. What your assistant sees is what your code will get.

### Docs your assistant can read

The server ships the full docs and the OpenAPI spec as MCP resources. When you ask for code, the assistant checks real field names first.

### Part of every plan

The MCP server is free and open source. Tool calls are normal API requests and count toward your 5,000 requests/hour.

## Questions about the MCP server

### What is the Odds API MCP server?

It is the official Model Context Protocol server for Odds-API.io. It gives AI assistants such as Claude, Codex and Cursor 25 tools to read live and historical odds, events, value bets, arbitrage and bet results from 450+ bookmakers.

### Which AI tools does it work with?

Any client that supports MCP over stdio. That includes Claude Code, Claude Desktop, Codex, Cursor, VS Code with GitHub Copilot, Windsurf and Zed. Claude Desktop also has a one-click install file.

### Do I need a paid plan?

Yes. The server needs an API key, and keys come with every paid plan, starting with Solo at £49/month for 2 bookmakers. The MCP server itself costs nothing extra.

### Which bookmakers can my assistant see?

The bookmakers selected on your plan. Ask the assistant to run get_selected_bookmakers to see them. Reference data such as sports, leagues and events is available for every bookmaker.

### Does it work with live odds?

Yes. get_live_events lists matches in play and get_odds returns their current prices. For a streaming feed in your own app, use the WebSocket API. The assistant can write that code for you.

### Is my API key safe?

The server runs on your computer and sends the key only to api.odds-api.io. There is no hosted proxy. The code is open source on GitHub under the MIT licence.

### Can the assistant place bets?

No. The server only reads data. It cannot log in to a bookmaker or place a bet.

### How is this different from the llms.txt docs?

llms.txt gives an assistant the documentation so it can write code. The MCP server lets it call the API and work with live data while you chat. Most people use both.

### At a glance

- Package: odds-api-mcp-server
- Install: npx, Docker or .mcpb
- Transport: stdio, runs locally
- Tools: 25
- Resources: API docs, OpenAPI spec
- Licence: MIT, open source
- Data: 450+ bookmakers, 34 sports

## Give your assistant live odds

Every plan includes the MCP server, 5,000 requests/hour and every sport and market. Pay monthly or yearly, and cancel any month.

[See plans](https://odds-api.io/pricing) · [AI setup guide](https://docs.odds-api.io/ai-vibe-coding) · [Claude tutorial](https://odds-api.io/blog/sports-betting-odds-api-mcp-claude)