OddsRelay
OfficialOddsRelay is a read-only MCP server that gives an AI assistant access to OddsRelay sports, bookmaker, coverage, matched-board odds, event odds, and usage data, with token-spending calls quoted first and capped by max_tokens.
List sport and competition keys with
sports, paged and free.List events for one sport with ids, paged and free.
List bookmaker and exchange keys with
bookmakers, free.Show which bookmakers cover which sports on a product and list market keys with
coverage, free and keyless.Read a matched board for one sport at named bookmakers with
odds, priced first and capped.Read one event’s prices at bookmakers/exchanges with
event_odds, priced first and capped, requiring raw-odds key scope.Check plan, token balance, reset time, and key scope with
usage, free.Narrow priced calls by sport, bookmakers, markets, exchanges, limits, regions, and commencement times.
Refuse token-spending calls above
max_tokensand report the quote so the assistant can ask before raising it.Keep API key only in
ODDSRELAY_KEY, send it only tohttps://api.oddsrelay.io, never expose it in replies/errors, and perform no writes, file access, or non-OddsRelay calls.
oddsrelay-mcp
An MCP server that gives an AI assistant read access to OddsRelay: matched boards, the prices for one event, and
the sport, event, bookmaker and coverage lists behind them. It is read-only, and every call that spends tokens is
priced first and refused above a per-call cap (max_tokens). The assistant is told to ask you before raising it.
It works with Claude Desktop, Claude Code, Cursor and any other client that starts MCP servers over stdio, and it is
built on the oddsrelay TypeScript client.
API docs: https://oddsrelay.io/docs
Get a key
Sign up at app.oddsrelay.io/signup and copy your key from the dashboard. Free gives you 50,000 tokens for 14 days from sign-up, with no card, then no tokens until you choose a plan, on the same key. Plans and token prices. Paid plans are for personal use. Any business, even one using the data only in-house, and any product that serves other people runs on Enterprise; a business can try the data on Free first.
Related MCP server: polymarket-mcp
Set up
You need an OddsRelay API key (Get a key, above). The server reads the key from ODDSRELAY_KEY. The bundle and the Gemini CLI extension set it for you; the other routes set it in your MCP client's config and need
Node 18 or later.
Claude Desktop (one-click bundle)
Download oddsrelay-mcp.mcpb from the latest release
and double-click it to install it in Claude Desktop, which asks for one setting: your API key. The setting is marked
sensitive, so Claude Desktop masks it, and it passes the key to the server as ODDSRELAY_KEY. The bundle carries
everything the server needs and runs on the Node built into Claude Desktop, so you need no Node of your own.
Claude Code
claude mcp add --transport stdio oddsrelay --env ODDSRELAY_KEY=your_key_here -- npx -y oddsrelay-mcpClaude Desktop (config file)
Settings, Developer, Edit Config opens claude_desktop_config.json. Add the server, then restart Claude Desktop:
{
"mcpServers": {
"oddsrelay": {
"command": "npx",
"args": ["-y", "oddsrelay-mcp"],
"env": { "ODDSRELAY_KEY": "your_key_here" }
}
}
}Cursor
Add the same mcpServers block to ~/.cursor/mcp.json (every project) or .cursor/mcp.json (one project).
The key sits in that config file as plain text, so keep the file out of anything you commit.
Gemini CLI
gemini extensions install https://github.com/oddsrelay/oddsrelay-mcpGemini CLI installs the extension from the latest release, then asks for your API key, keeps it in your system
keychain and passes it to the server as ODDSRELAY_KEY. The extension also loads the Agent Skill below.
First questions
Ask your assistant:
Using OddsRelay, which bookmakers carry tennis on the standard board?
That calls coverage, which costs no tokens. Then:
Show the OddsRelay standard board for soccer at Ladbrokes and William Hill, first five events.
The assistant finds the bookmaker keys with bookmakers, then calls odds, which is priced before it runs.
Agent Skill
skills/oddsrelay/SKILL.md is an Agent Skill for assistants that load skills (Claude
Code, Claude.ai and other skill-aware clients): when to reach for OddsRelay, how to quote a call before it spends
tokens, and how to read the boards. It works with this server or with plain HTTPS.
Tools
Tool | What it reads | Tokens |
| Sport and competition keys, paged | none |
| The events of one sport, with their ids, paged | none |
| Bookmaker and exchange keys | none |
| Which bookmakers carry which sports on one product, and the product's market keys | none |
| A matched board ( | priced first, capped |
| One event's prices at each bookmaker and exchange carrying it, narrowed to the bookmakers and markets you name | priced first, capped |
| Your plan, token balance, reset time and key scope | none |
The token cap
odds and event_odds take a max_tokens argument with a small default. Before each call the server asks the
API what the call would cost (a quote, which spends nothing). If it would cost more than max_tokens, the server
makes no call, spends nothing and tells the assistant the price, so the assistant can narrow the filters or ask you
before it tries again with a higher max_tokens.
odds always takes one sport and the bookmakers you name, so each call stays narrow. The cost is set by the filters
you send; cutting the reply to limit rows does not change it. Every reply from these two tools carries tokens:
what the call cost and what is left.
Both tools only read, but their MCP annotations mark them as calls with a cost rather than read-only, so a client
that asks before such calls will ask you each time. event_odds reads the raw board, so it needs a key that can read raw odds.
Replies
Replies are compact JSON. Long lists are cut to limit rows (each tool has its own default) and to a size an
assistant can read in one go, with a more note saying how many rows were left out and what to change to see them.
Paged tools return next_cursor, which the assistant passes back as cursor; a page cut short goes on from the
first row not shown.
Errors come back as tool errors with the API's error code and, where the API sends them, the values it accepts:
ask for an unknown bookmaker and the error lists the keys it accepts.
Your key
The server reads the key only from ODDSRELAY_KEY and sends it only to https://api.oddsrelay.io, in the
Authorization header. It never puts the key in a tool reply or an error: if an error ever echoed it, it would be
replaced with [hidden]. The server logs nothing.
What it does not do
No tool writes anything, reads or writes files, or calls any host but the OddsRelay API.
Develop
npm ci
npm testThe tests run the server against a stubbed fetch and make no network calls. npm run bundle builds
oddsrelay-mcp.mcpb from dist and the installed dependencies: manifest.json describes the bundle, and
.mcpbignore keeps sources, tests and development packages out of it. To try the built server by hand,
npx @modelcontextprotocol/inspector node dist/cli.js opens it in the MCP Inspector.
More from OddsRelay
oddsrelay-python: the Python client,
pip install oddsrelayoddsrelay-js: the JavaScript and TypeScript client,
npm install oddsrelayoddsrelay-r: the R client
oddsrelay-sheets: formulas and a template spreadsheet for Google Sheets
examples: short programs to copy, one folder each
Libraries and tools, the docs, the API reference and the OpenAPI file
Contact: hello@oddsrelay.io
License
MIT
Available Tools
7 toolsbookmakersBookmakersARead-only
Lists the bookmaker and exchange keys that odds, event_odds and coverage take. Costs no tokens.
Inputs: no named parameters.
coverageCoverageARead-only
Shows which bookmakers carry which sports on one product, and that product's market keys (the values odds takes as markets). Filter by bookmaker or sport. Costs no tokens and sends no key.
Inputs: limit, sport, region, product, +1 more.
event_oddsEvent oddsA
Reads one event's prices (id from events or odds) at each bookmaker and exchange carrying it, narrowed to the bookmakers and markets you name. Needs a key that can read raw odds. Spends tokens: priced first, and refused when it would cost more than max_tokens.
Inputs: id (required), limit, region, markets, +2 more.
eventsEventsARead-only
Lists the events of one sport with their ids, for event_odds. Costs no tokens. Paged: pass next_cursor back as cursor.
Inputs: sport (required), limit, cursor, region, +2 more.
oddsOddsA
Reads a matched board (bookmaker back prices with exchange lay prices) for one sport at the bookmakers you name. Spends tokens: priced first, and refused when it would cost more than max_tokens.
Inputs: type (required), sport (required), bookmakers (required), limit, +6 more.
sportsSportsARead-only
Lists sport and competition keys (such as soccer or soccer_epl) for the sport filter of odds and events. Costs no tokens. Paged: pass next_cursor back as cursor.
Inputs: limit, cursor, region.
usageUsageARead-only
Shows this key's plan, token balance, reset time and scope. Costs no tokens.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct aspect: discovery (sports, events, bookmakers, coverage), price retrieval (odds, event_odds), and account info (usage). Minor overlap exists between bookmakers (key list) and coverage (mapping + markets), and between odds (sport-level) and event_odds (event-level), but descriptions clarify the granularity.
All tools are lowercase resource nouns (sports, events, bookmakers, coverage, odds, usage) with one snake_case compound (event_odds). Style is consistent and readable, though it deviates from a strict verb_noun pattern. Plural/singular mix is minor.
7 tools are well-scoped for a read-only odds API: four discovery tools, two price retrieval tools, and one account tool. No redundant or missing tools at this count.
Covers the full read lifecycle: discovering sports, events, bookmakers, coverage/market keys, and fetching odds at sport and event level, plus usage. Minor gap: no dedicated tool to list market keys independently (bundled into coverage with bookmaker-sport mapping).
Maintenance
Related MCP Connectors
Read-only MCP server for The Quiet Protocol's engines, benchmarks, proof, and business data.
Historical tick, order book and settlement data for Polymarket and Predict.fun crypto up/down markets, plus smart-money lists and backtest quotes, over a read-only MCP server.
Read-only MCP server exposing a user ORANO library to their own AI agent.
Hosted MCP server for SEC, FRED, Polymarket, Deribit, OKX, and FMP.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP-compatible server that gives AI agents access to alternative sports data across 30+ leagues — odds, events, probabilities, settlement, and futures for prediction markets, DFS platforms, and sportsbooks.2918 PyPIMIT
- AlicenseAqualityCmaintenanceA read-only MCP server exposing Polymarket's public prediction-market data. Search markets, read live odds and order books, pull historical probability time-series, and inspect public wallet positions.14MIT
- AlicenseCqualityBmaintenanceRead-only MCP server that exposes public TokenLab model catalog tools for agents to discover models, inspect request contracts, and compare pricing.321,219 npm1MIT
- AlicenseNot gradedqualityDmaintenancePublic read-only MCP server exposing today's free sports-betting projections, track record, methodology, engine versions, and per-game model reads from the Olympus Bets Analytics platform.MIT