Odds-API MCP Server
OfficialThis MCP server gives AI agents access to Odds-API.io sports betting odds, event data, analysis, settlement, and historical/closing-line tools.
Discover sports, leagues, exact market names, bookmakers, participants, and bookmaker selections.
Find upcoming, live, and historical events by sport, league, team, date, or search query.
Fetch prematch/live odds for one or multiple events, with market filtering and compact responses.
Get odds summaries with best/average/median/worst/fair prices, odds movements, and recently changed odds.
Identify value bets, arbitrage opportunities, and dropping odds at bookmakers.
Retrieve historical odds, closing lines, closing-line value data, and backtest-ready settled event data.
Settle events and grade up to 50 bets as won, lost, void, half won/lost, pending, or ungradeable.
Access golf outright tournament odds and results, including Winner, Top N, ties, and Make Cut markets.
Map events and selections to bookmaker IDs such as Polymarket or Kalshi.
Check hourly request quota/usage and fetch full API documentation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Odds-API MCP Server Show me upcoming Premier League matches"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Odds-API.io MCP Server
MCP server for the Odds-API.io sports betting odds API. It gives Claude, Cursor, VS Code and other AI agents live and pre-match odds from 450+ bookmakers across 34 sports, plus odds summaries, closing lines, bet settlement, golf outrights, value bets, arbitrage and dropping odds.
Quickstart
Get an API key at odds-api.io/pricing.
Add the server to Claude Code:
claude mcp add odds-api --env ODDS_API_KEY="your-api-key" -- npx -y odds-api-mcp-serverAsk: "Show me upcoming Premier League matches with Bet365 odds."
Setup for Claude Desktop, Cursor and VS Code is below.
Related MCP server: SportWizzard MCP Server
Get an API key
The server needs an Odds-API.io API key from a paid plan. Pick a plan at odds-api.io/pricing, then pass the key as the ODDS_API_KEY environment variable.
Documentation
Features
33 tools covering every public Odds-API.io v3 REST endpoint: sports, markets, events, odds, odds summaries, line movements, value bets, arbitrage, dropping odds, historical events and odds, closing lines, bet settlement, golf outrights, participants, bookmaker id mappings and request quota. The WebSocket stream and the participant logo image are not tools; use the REST equivalents.
Built for agents: every tool says what to call first, what plan or add-on it needs and what it returns. Read tools carry
readOnlyHint; onlyselect_bookmakersandclear_selected_bookmakerschange anything.Small responses: compact JSON, a
marketsfilter on every odds tool (market names per sport: odds-api.io/markets), andfields/maxResultson list tools.Clear errors: a 403 (missing plan or add-on) or 429 (hourly limit) comes back with the API's own message and an instruction not to retry blindly.
Key safety: the key is read from
ODDS_API_KEYonly. No tool takes it as an argument, and it is masked as***in every output and error.Agent guide in
skills/odds-api/SKILL.md: call order, caching, quotas and 429 handling. Also served as theodds-api://guideresource and, in short form, as the server'sinstructions.
Install in your client
One-Click Install (Claude Desktop)
Download the latest .mcpb file from Releases and open it. Claude Desktop will prompt you for your API key.
Claude Code CLI
claude mcp add odds-api --env ODDS_API_KEY="your-api-key" -- npx -y odds-api-mcp-serverClaude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"odds-api": {
"command": "npx",
"args": ["-y", "odds-api-mcp-server"],
"env": {
"ODDS_API_KEY": "your-api-key"
}
}
}
}Cursor
Add to your Cursor MCP settings (.cursor/mcp.json in your project or global config):
{
"mcpServers": {
"odds-api": {
"command": "npx",
"args": ["-y", "odds-api-mcp-server"],
"env": {
"ODDS_API_KEY": "your-api-key"
}
}
}
}VS Code
Add to your VS Code settings (.vscode/mcp.json):
{
"servers": {
"odds-api": {
"command": "npx",
"args": ["-y", "odds-api-mcp-server"],
"env": {
"ODDS_API_KEY": "your-api-key"
}
}
}
}Global Install (alternative)
npm install -g odds-api-mcp-serverThen use odds-api-mcp-server as the command instead of npx -y odds-api-mcp-server.
Configuration
Variable | Required | Description |
| Yes | Your API key from a paid plan at odds-api.io/pricing |
Requests go to https://api.odds-api.io/v3. Each tool call is one API request against your hourly limit (multi-event tools count as one).
Available Tools
Catalogue
Tool | Description |
| List sports and their slugs. Call first |
| Leagues for a sport ( |
| Exact market names per sport, with shape, period and prematch/live flags |
| All bookmakers with |
| Bookmakers selected on your key |
| Add bookmakers to your selection (writes) |
| Clear your selection, once per 12h (destructive) |
Events
Tool | Description |
| Events with league, status (pending, live, settled, cancelled), date, participant and bookmaker filters, |
| One event with scores and live clock |
| Events in play now |
| Search by team or league name, |
Odds
Tool | Description |
| Odds for one event; pass |
| Odds for up to 10 events in one request, with |
| Best, average, median, worst and fair price per line across bookmakers, for one or up to 10 events (Growth plan and above) |
| Opening, latest and every change for one market at one bookmaker |
| Odds changed since a timestamp, for named markets (max 40), with |
Analysis
Tool | Description |
| Prices above a fair-odds estimate for a bookmaker, by sport and league. |
| Arbitrage across your bookmakers with |
| Biggest drops at sharp bookmakers by sport, league, market and time window |
Historical and closing lines
Tool | Description |
| Finished events for a league and date range |
| Finished events by team name |
| Closing odds and final score for one event, with |
| Closing odds for every settled event across up to 10 leagues and 366 days |
Settlement
Tool | Description |
| Status, final score and |
| Grade up to 50 bets as won, lost, void, half won, half lost, pending or ungradeable |
Outrights (golf)
Tool | Description |
| Tournaments for a sport (golf: PGA Tour, DP World Tour, LIV Golf, majors) |
| Winner, Top 5/10/20, Top N (Incl. Ties) and Make Cut odds, with |
| Positions, cut status and winners per market |
Participants and mappings
Tool | Description |
| Teams or players for a sport |
| One team or player by ID |
| Our events and selections mapped to bookmaker ids (Polymarket, Kalshi), lookup or bulk sync with cursor |
Account and reference
Tool | Description |
| Hourly request limit, remaining requests and reset time |
| Fetch the full API documentation |
Outrights
Golf outright odds and results are the Outrights add-on on paid plans. Call list_outrights with sport: "golf" for tournament ids, then get_outright_odds with the id and your bookmakers. Markets: Winner, Top 5, Top 10, Top 20 (boundary ties under the bookmaker's dead-heat rules), Top 5 (Incl. Ties), Top 10 (Incl. Ties), Top 20 (Incl. Ties) (ties paid in full) and Make Cut (only for events with a cut). A full field is 150+ golfers per market, so pass markets and maxRunners. get_outright_results lists every golfer's position and the winners per market once the tournament is settled.
Without the add-on the API answers 403 with a link to enable it; the server passes that message through and tells the agent to relay it rather than retry.
Closing lines
get_closing_lines returns closing odds for every settled event across up to 10 leagues in one request, over up to 366 days, so a season fits in one sweep (100 events per response; page with limit and skip). Use it for closing line value (CLV) and model backtests. For a single match use search_historical_events and get_historical_odds. Paid plans.
Prompts
Prompt | Description |
| Find a match and compare prices across your bookmakers |
| Grade a list of bets against final results |
| Show golf tournament prices for a market |
Resources
Resource URI | Description |
| Agent guide: call order, caching, quotas, errors |
| Complete API documentation |
| OpenAPI specification |
Example Usage
Once configured, ask your AI assistant things like:
"Show me upcoming Premier League matches"
"Get ML and totals odds for the next Arsenal match from Bet365 and SingBet"
"Where is the best price on the Lakers game, and what is the fair price?"
"Find value bets on Bet365 in baseball"
"Are there arbitrage opportunities over 1% between Bet365 and Unibet in football?"
"Show me how the spread moved for event 12345"
"Give me Premier League closing lines for last season from Bet365"
"Did these three bets win?"
"Who is favourite to win the next PGA Tour event, and what are the Top 10 prices?"
"How many requests do I have left this hour?"
Development
git clone https://github.com/odds-api-io/odds-api-mcp-server
cd odds-api-mcp-server
npm install
npm run build
npm testLicense
MIT
Links
Odds-API.io - Main website
Documentation - API docs and guides
API Reference - Swagger/OpenAPI
npm - Package registry
Available Tools
33 toolsclear_selected_bookmakersClear bookmaker selectionADestructiveIdempotent
Remove every bookmaker from this API key's selection (destructive). Allowed once every 12 hours, so only call it when the user explicitly asks.
Inputs: no named parameters.
get_arbitrage_betsArbitrage opportunitiesARead-onlyIdempotent
Price gaps across the named bookmakers where the best price for every outcome implies a total probability under 100%. Prematch only, sorted by profitMargin (already a percentage after exchange fees: 2.48 means 2.48%, do not multiply by 100), with stake split (optimalStakes), stake limits (maxStake) and bet links. Prices move fast and bookmakers can void or limit bets, so present results as calculated margins at the quoted prices, never as guaranteed.
Inputs: bookmakers (required), limit, sport, league, +4 more.
get_bookmakersList bookmakersARead-onlyIdempotent
List all bookmakers with name, active, createdAt, status (ok, degraded, down) and reason (maintenance, unavailable, or null). Use status/reason to explain why a bookmaker has no odds: a 'down' bookmaker is left out of odds, value bets and arbitrage until it recovers.
Inputs: fields, maxResults.
get_closing_linesClosing linesARead-onlyIdempotent
Closing odds for every settled event across up to 10 leagues in one request, for closing line value (CLV) and model backtests. Date range up to 366 days, so a season fits in one sweep; at most 100 events per response, page with limit and skip. Paid plans. Each event is shaped like get_historical_odds.
Inputs: to (required), from (required), sport (required), leagues (required), +4 more.
get_documentationAPI documentationARead-onlyIdempotent
Fetch the complete Odds-API.io documentation as plain text (large). Use it for questions the tool descriptions do not answer, such as WebSocket details or market rules.
Inputs: no named parameters.
get_dropping_oddsDropping oddsARead-onlyIdempotent
Odds that dropped the most from opening at sharp bookmakers, with drop percentages since opening and over 12h, 24h and 48h. Refreshed every few seconds. Paid plans. For player prop markets, market.label holds the player name. Always pass sport when the user mentions or implies one: without it results are dominated by player props.
Inputs: page, sort, limit, sport, +6 more.
get_eventGet eventARead-onlyIdempotent
Get one event by ID, including scores and, when live, the match clock. Score periods use keys p1..pN, ft, ot and ap (older keys period1, overtime, penalties, fulltime stop on 12 November 2026).
Inputs: id (required).
get_eventsList eventsARead-onlyIdempotent
List events for a sport (default window: the next 14 days, max 5000 per response). Call get_sports and get_leagues first for slugs. Returns id, home, away, homeId, awayId, date, status, sport, league and scores; use the id with get_odds. Use fields (e.g. 'id,home,away,date') and limit to keep the list short. Score periods use keys p1..pN, ft, ot and ap (older keys period1, overtime, penalties, fulltime stop on 12 November 2026).
Inputs: sport (required), to, from, skip, +6 more.
get_historical_eventsHistorical eventsARead-onlyIdempotent
Finished events for one sport and league in a date range (max 31 days; data from December 2025). Use the ids with get_historical_odds. To find a past match by team name use search_historical_events instead. Score periods use keys p1..pN, ft, ot and ap (older keys period1, overtime, penalties, fulltime stop on 12 November 2026).
Inputs: to (required), from (required), sport (required), league (required), +2 more.
get_historical_oddsHistorical oddsARead-onlyIdempotent
Closing odds and the final score for one finished event, same shape as get_odds. Get the id from get_historical_events or search_historical_events. Pass markets to keep the response small.
Inputs: eventId (required), bookmakers (required), markets.
get_leaguesList leaguesARead-onlyIdempotent
List leagues for a sport with name, slug and active event count. Call get_sports first for the sport slug; use the league slug in get_events and other tools.
Inputs: sport (required), all, fields, maxResults.
get_live_eventsList live eventsARead-onlyIdempotent
List events in play now with scores and the match clock, optionally for one sport. Pass sport and fields to keep the response small.
Inputs: sport, fields, maxResults.
get_mappingsBookmaker id mappingsARead-onlyIdempotent
Map our events and selections to a bookmaker's own event, market and outcome ids (for example Polymarket conditionId and token id, or Kalshi tickers), joinable to get_odds on (eventId, market, hdp, side). Look up by eventId(s), marketId(s) or outcomeId; with none of these it is a bulk sync of upcoming and live events, paged with cursor until nextCursor is null. Paid plans; the bookmaker must be in the key's selection.
Inputs: bookmaker (required), limit, sport, active, +9 more.
get_marketsList market namesARead-onlyIdempotent
List the exact market names served per sport, with shape (moneyline, line, outcomes, yesno, labelled), period, and whether each is served prematch and live. Call it before passing markets to any odds tool; names must match in full, e.g. 'ML' not 'Match Winner', 'Totals' not 'Over/Under'. Omitting sport returns every sport (large).
Inputs: sport, fields.
get_multi_oddsGet odds for several eventsARead-onlyIdempotent
Get odds for up to 10 events in one request (counts as one request). Always pass markets to keep the response small. Same shape as get_odds, as an array.
Inputs: eventIds (required), bookmakers (required), markets.
get_oddsGet odds for an eventARead-onlyIdempotent
Get odds for one event from the named bookmakers, grouped by bookmaker then market, with bet links. Always pass markets (e.g. 'ML,Spread,Totals'): without it every market from every bookmaker comes back, which can be very large. Get the event id from get_events or search_events and market names from get_markets. For best/average prices across all books, get_odds_summary is more compact.
Inputs: eventId (required), bookmakers (required), markets.
get_odds_movementsOdds movementsARead-onlyIdempotent
Opening price, latest price and every recorded change for one market of one event at one bookmaker (prematch only, timestamps in Unix ms). Leave marketLine out for the main line. A 404 says what is missing and lists the markets or lines that do have history; use those.
Inputs: market (required), eventId (required), bookmaker (required), marketLine.
get_odds_summaryOdds summary (best, average, fair)ARead-onlyIdempotent
Best, average, median, worst and margin-free fair price per market line across bookmakers, with which bookmakers have the best price. The compact way to answer 'where is the best price' or 'what is the fair price'. Pass one eventId, or up to 10 comma-separated ids (one request). Growth plan and above; lower plans get a sample response marked demo: true, which is not real data, so tell the user.
Inputs: eventId (required), lines, markets, bookmakers, +1 more.
get_outright_oddsOutright oddsARead-onlyIdempotent
Prices for one outright tournament from the named bookmakers. Golf markets: Winner, Top 5, Top 10, Top 20 (boundary ties under dead-heat rules), Top 5 (Incl. Ties), Top 10 (Incl. Ties), Top 20 (Incl. Ties) (ties paid in full) and Make Cut (only events with a cut). Runners carry label, participantId and odds (+ layOdds on exchanges), or yes/no for Make Cut, sorted shortest price first. A full field is large: pass markets and maxRunners. Needs the Outrights add-on: a 403 means the key does not have it, so tell the user the message and do not retry.
Inputs: id (required), bookmakers (required), markets, maxRunners.
get_outright_resultsOutright resultsARead-onlyIdempotent
Final results for one outright tournament: each golfer's position (shared when tied, null when cut, withdrawn or disqualified), madeCut and status, plus winners per market (Winner, Top N, Top N (Incl. Ties), Make Cut). Empty until the tournament is settled. Dead-heat and each-way terms are the bookmaker's rules. Needs the Outrights add-on (403 without it: tell the user, do not retry).
Inputs: id (required).
get_participantGet participantARead-onlyIdempotent
Get one team or player by ID.
Inputs: id (required).
get_participantsList participantsARead-onlyIdempotent
Teams or players for a sport, optionally filtered by name. Returns id and name (esports also game and shortCode). Use the id as participantId in get_events.
Inputs: sport (required), fields, search, maxResults.
get_selected_bookmakersShow selected bookmakersARead-onlyIdempotent
Show the bookmakers selected on this API key. Odds tools only return bookmakers in this selection; the plan sets how many can be selected.
Inputs: no named parameters.
get_settlementsEvent settlementsARead-onlyIdempotent
What happened in up to 50 events: status (pending, live, awaiting_result, settled, cancelled), final score by period and a final flag (true = stop polling). Unknown ids are listed in notFound. Paid plans. Score periods use keys p1..pN, ft, ot and ap (older keys period1, overtime, penalties, fulltime stop on 12 November 2026).
Inputs: eventIds (required).
get_sportsList sportsARead-onlyIdempotent
List every sport with its name and slug. Call this first: other tools take the slug (e.g. 'football', 'american-football'). No plan needed.
Inputs: no named parameters.
get_updated_oddsOdds changed sinceARead-onlyIdempotent
Odds that changed since a Unix timestamp (at most 90 seconds old) for one bookmaker and sport, limited to the markets you name. A delta: only changed markets are returned. For polling code, not for one-off questions (use get_odds instead).
Inputs: since (required), sport (required), markets (required), bookmaker (required), +1 more.
get_usageRequest quotaARead-onlyIdempotent
Hourly request limit, requests remaining and reset time for this API key, read from the rate-limit headers of the latest API call in this session. If no call has been made yet it calls get_sports once, which counts as one request. Use it to plan bulk work or to explain a 429.
Inputs: no named parameters.
get_value_betsValue betsARead-onlyIdempotent
Prices at one bookmaker that sit above a fair-odds estimate from market consensus, with expectedValue, betSide, the bookmaker's odds and bet link. Prematch, refreshed every few seconds. Filter by sport and league and use maxResults to keep the list short. expectedValue is bookmaker/fair x 100; edge % = expectedValue - 100 (103.42 is a 3.42% edge, below 100 is a negative edge). Never multiply it by 100. Expected value is an estimate, not a guaranteed outcome.
Inputs: bookmaker (required), sport, fields, league, +2 more.
grade_betsGrade betsARead-onlyIdempotent
Settle up to 50 bets: each is graded won, lost, void, half_won, half_lost, pending or ungradeable, with a reason, a final flag and the score it used. Describe each bet with the fields of an odds row from get_odds (market name as served, side, hdp, label). Football settles on 90 minutes. Re-send non-final selections at most once a minute. Read-only: it does not place or change anything. Paid plans.
Inputs: selections (required).
list_outrightsList outright tournamentsARead-onlyIdempotent
List outright (futures) tournaments for a sport, sorted by date: id, name, date, status, league and bookmakerCount (0 = not priced yet). Golf only today: PGA Tour, DP World Tour, LIV Golf and the majors. Call this first, then get_outright_odds with the id. Needs the Outrights add-on: a 403 means the key does not have it, so tell the user the message (it links to where to add it) and do not retry.
Inputs: sport (required), fields, league, status, +1 more.
search_eventsSearch eventsARead-onlyIdempotent
Find events by team or league name (case- and accent-insensitive, min 3 characters). Returns up to 10 results ranked by relevance. The quickest way from a team name to an event id.
Inputs: query (required), status.
search_historical_eventsSearch historical eventsARead-onlyIdempotent
Find finished events by team name across all leagues, optionally for one sport. Date span max 31 days (default: the last 31 days). Returns up to 100 events, newest first. Use the ids with get_historical_odds.
Inputs: query (required), to, from, sport, +2 more.
select_bookmakersAdd bookmakers to selectionAIdempotent
Add bookmakers to this API key's selection (changes account state). Only call when the user asks to change their bookmakers; the plan caps how many can be selected.
Inputs: bookmakers (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Most tools target clearly distinct resources and actions, and the descriptions explicitly guide selection between close pairs such as get_events, get_live_events, search_events, and get_historical_events. The main ambiguity is the dense cluster of odds tools (get_odds, get_odds_summary, get_historical_odds, get_closing_lines, get_odds_movements), which requires careful reading but is still reasonably well signposted.
Tool names consistently use snake_case and a predictable verb_noun shape such as get_events, search_events, get_odds, select_bookmakers, and grade_bets. The only minor variation is list_outrights instead of get_outrights, which is logical and does not break the pattern.
With 33 tools, the surface is well above the typical 3-15 range and feels heavy even for a broad sports odds API. The domain is rich enough to justify several categories, but many specialized odds, historical, outright, and mapping tools make the set cumbersome for an agent to navigate.
The tool set covers the domain comprehensively: sports/leagues/events/participants, live and historical data, multiple odds views, bookmaker selection, value/arbitrage/dropping odds, settlements, bet grading, outrights, mappings, and documentation. There are no obvious dead ends for a read-only sports odds and market-data API.
Maintenance
Related MCP Connectors
Sports odds, player props and source coverage for AI assistants. Connect with your own API key.
Live odds, cross-book +EV and graded player-prop results across 37 books. Hosted endpoint included.
Sports prediction markets for AI agents — live prices, quotes, orders, and positions.
Real-time sports betting data: odds, player props, edges and arbitrage from 35+ books and DFS apps.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables fetching sportsbook odds, live scores, and event information across 70+ books and 30+ leagues, with tools to list sports, get scores, and discover events.108 npm1MIT
- AlicenseAqualityBmaintenanceEnables AI agents to query live sports betting data including odds, edges, arbitrage opportunities, player/team stats, and reference data using the SportWizzard API.20132 npmMIT
- AlicenseAqualityCmaintenanceProvides AI assistants with sports model win probabilities and fair odds across nine sports without requiring an API key.354 npmMIT
- AlicenseBqualityDmaintenanceProvides AI agents with live, grounded sports data including model probabilities, track records, and European soccer and tennis arbitrage opportunities, so they answer from real numbers instead of stale guesses.1368 npm1MIT