rapidoddsapi-mcp 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,9 @@
1
+ """MCP server for RapidOddsAPI.
2
+
3
+ Exposes bookmaker odds, live scores, arbitrage and value bets as MCP tools,
4
+ backed by the official `rapidoddsapi` SDK.
5
+ """
6
+
7
+ __version__ = "0.1.0"
8
+
9
+ __all__ = ["__version__"]
@@ -0,0 +1,4 @@
1
+ from .server import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
@@ -0,0 +1,85 @@
1
+ """Which bookmakers to ask for when the caller does not say.
2
+
3
+ Credits are `market_types x ceil(bookmakers / 5)`, so five bookmakers is one
4
+ group and the cheapest useful request. Picking them by region matters: asking
5
+ US books about the AFL returns nothing and still risks a charge on another
6
+ sport, and line shopping only works across books that actually price the game.
7
+ """
8
+
9
+ from collections.abc import Sequence
10
+
11
+ # Five per region, one credit group. Deliberately mixed rather than the five
12
+ # biggest, since arbitrage and value both need books that disagree.
13
+ AU_DEFAULT = ("Sportsbet", "TAB", "Ladbrokes", "Bet365", "Pointsbet")
14
+ US_DEFAULT = ("DraftKings", "BetMGM", "Fanatics", "Bet365", "Bovada")
15
+ EU_DEFAULT = ("Pinnacle", "Bet365", "Unibet", "Sportsbet", "TAB")
16
+
17
+ _REGIONS = {
18
+ "AFL": AU_DEFAULT,
19
+ "NRL": AU_DEFAULT,
20
+ "NFL": US_DEFAULT,
21
+ "NBA": US_DEFAULT,
22
+ "WNBA": US_DEFAULT,
23
+ "MLB": US_DEFAULT,
24
+ "NHL": US_DEFAULT,
25
+ }
26
+
27
+ # Soccer and tennis are priced best by the European books, and every sport not
28
+ # named above falls into that bucket.
29
+ _FALLBACK = EU_DEFAULT
30
+
31
+ # A sharp book prices close to true probability, which is what value betting
32
+ # measures against. Pinnacle is the one this API carries.
33
+ SHARP_BOOKMAKER = "Pinnacle"
34
+
35
+ # Arbitrage needs disagreement between books, so it looks wider than a plain
36
+ # odds request. Ten books is two credit groups.
37
+ ARBITRAGE_DEFAULT_COUNT = 10
38
+
39
+
40
+ def default_bookmakers(sport: str) -> tuple[str, ...]:
41
+ """The five books to use for a sport when the caller did not choose."""
42
+ return _REGIONS.get(sport.upper(), _FALLBACK)
43
+
44
+
45
+ def wide_bookmakers(
46
+ sport: str,
47
+ count: int = ARBITRAGE_DEFAULT_COUNT,
48
+ must_include: Sequence[str] = (),
49
+ ) -> Sequence[str]:
50
+ """A wider spread for the tools that compare books against each other.
51
+
52
+ Starts from the sport's region, then tops up from the other regions with
53
+ feeds that carry most sports, skipping duplicates.
54
+
55
+ `must_include` is seeded first and counts towards the total rather than
56
+ being added on top, so requiring the sharp book does not quietly push the
57
+ list over a credit group boundary.
58
+ """
59
+ from rapidoddsapi import AU_BOOKMAKERS, EU_BOOKMAKERS, US_BOOKMAKERS
60
+
61
+ region = default_bookmakers(sport)
62
+ region_pool: dict[tuple[str, ...], Sequence[str]] = {
63
+ AU_DEFAULT: AU_BOOKMAKERS,
64
+ US_DEFAULT: US_BOOKMAKERS,
65
+ EU_DEFAULT: EU_BOOKMAKERS,
66
+ }
67
+
68
+ picked = list(must_include)
69
+ picked += [book for book in region if book not in picked]
70
+ first = region_pool[region]
71
+ for pool in (first, EU_BOOKMAKERS, AU_BOOKMAKERS, US_BOOKMAKERS):
72
+ for book in pool:
73
+ if len(picked) >= count:
74
+ return picked
75
+ if book not in picked:
76
+ picked.append(book)
77
+
78
+ return picked
79
+
80
+
81
+ def with_sharp(bookmakers: Sequence[str]) -> Sequence[str]:
82
+ """Guarantee the sharp book is in the list, since value is measured off it."""
83
+ if SHARP_BOOKMAKER in bookmakers:
84
+ return bookmakers
85
+ return [SHARP_BOOKMAKER, *bookmakers]
@@ -0,0 +1,209 @@
1
+ """Turn API responses into the text a model reads back.
2
+
3
+ Plain text rather than raw JSON, because these responses nest four levels deep
4
+ and the useful comparison, one selection priced across several books, is spread
5
+ across all of them. Flattening it is the difference between a model spotting
6
+ the best price and not.
7
+ """
8
+
9
+ from collections.abc import Mapping, Sequence
10
+ from typing import Any
11
+
12
+ from rapidoddsapi import group_games
13
+ from rapidoddsapi.types import Arbitrage, OddsResponse, ResultsResponse, Usage, ValueBet
14
+
15
+ # A selection is its name plus, on markets with a line, the line itself. Totals
16
+ # quote "Over" at several points and they are different bets.
17
+ Selection = tuple[str, float | None]
18
+
19
+
20
+ def credit_line(cost: int, usage: Usage | None) -> str:
21
+ """The spend footer every tool ends with.
22
+
23
+ Always present, so the model can see what it is burning and slow down on
24
+ its own. `usage` is optional because a balance lookup failing should not
25
+ take the actual answer down with it.
26
+ """
27
+ spent = f"Cost: {cost} credit{'s' if cost != 1 else ''}."
28
+
29
+ if usage is None:
30
+ return spent
31
+
32
+ remaining = usage["credits_remaining"]
33
+ limit = usage["credits_limit"]
34
+ balance = f" Balance: {remaining:,} of {limit:,} remaining."
35
+ if not usage["resets"]:
36
+ balance += " These do not reset."
37
+ return spent + balance
38
+
39
+
40
+ def format_odds(response: OddsResponse, bookmakers: Sequence[str]) -> str:
41
+ """Odds grouped by game, then market, then selection, best price first.
42
+
43
+ The API returns one entry per bookmaker, so the same fixture arrives once
44
+ per book. `group_games` merges them on teams plus a time window, which is
45
+ what makes the cross book comparison possible at all. A window rather than
46
+ an equality check because books disagree on the start time, sometimes by
47
+ an hour.
48
+ """
49
+ if not response.get("games"):
50
+ return ""
51
+
52
+ games = group_games(response)
53
+ books = ", ".join(bookmakers)
54
+ lines = [f"{response.get('sport', 'Unknown')} — {len(games)} game(s), from {books}", ""]
55
+
56
+ for entry in games:
57
+ game = entry["game"]
58
+ lines.append(f"{game.get('away_team')} at {game.get('home_team')} {_when(game)}")
59
+
60
+ for market, prices in _by_market(entry).items():
61
+ lines.append(f" {market}")
62
+ for (name, point), quotes in prices.items():
63
+ quotes.sort(key=lambda q: q[0], reverse=True)
64
+ label = name if point is None else f"{name} {point:+g}"
65
+ best_price, best_book = quotes[0]
66
+ rest = ", ".join(f"{book} {price}" for price, book in quotes[1:])
67
+ line = f" {label:<28} {best_price} ({best_book})"
68
+ lines.append(f"{line} {rest}" if rest else line)
69
+ lines.append("")
70
+
71
+ return "\n".join(lines).rstrip()
72
+
73
+
74
+ def format_arbitrage(found: list[Arbitrage], stake: float) -> str:
75
+ if not found:
76
+ return ""
77
+
78
+ lines = [f"{len(found)} arbitrage opportunit{'y' if len(found) == 1 else 'ies'}:", ""]
79
+ for arb in found:
80
+ lines.append(
81
+ f"{arb['away_team']} at {arb['home_team']} +{arb['profit_percent']:.2f}% "
82
+ f"on a {stake:g} stake"
83
+ )
84
+ for leg in arb["legs"]:
85
+ lines.append(
86
+ f" {leg['team']:<28} {leg['price']} @ {leg['bookmaker']} "
87
+ f"stake {leg['stake']:g}"
88
+ )
89
+ lines.append("")
90
+
91
+ lines.append(
92
+ "Prices move while the second leg is being placed, so an edge this small "
93
+ "may not survive. Check both are still live before betting."
94
+ )
95
+ return "\n".join(lines)
96
+
97
+
98
+ def format_value_bets(found: list[ValueBet], sharp: str) -> str:
99
+ if not found:
100
+ return ""
101
+
102
+ lines = [f"{len(found)} value bet(s), priced against {sharp}:", ""]
103
+ for bet in found:
104
+ lines.append(
105
+ f"+{bet['edge_percent']:.2f}% {bet['selection']} {bet['price']} @ {bet['bookmaker']}"
106
+ )
107
+ lines.append(
108
+ f" {bet['away_team']} at {bet['home_team']} "
109
+ f"fair price {bet['fair_price']:.2f} "
110
+ f"({bet['fair_probability'] * 100:.1f}% implied)"
111
+ )
112
+ lines.append("")
113
+ lines.append(
114
+ f"Edge is measured off {sharp} with its margin removed. It is an estimate of "
115
+ "value, not a guaranteed win."
116
+ )
117
+ return "\n".join(lines)
118
+
119
+
120
+ def format_results(response: ResultsResponse) -> str:
121
+ games = response.get("games", [])
122
+ if not games:
123
+ return ""
124
+
125
+ lines = [f"{response.get('sport', 'Unknown')} — {len(games)} game(s)", ""]
126
+
127
+ for game in games:
128
+ info = game.get("game", {})
129
+ status = info.get("status", "UNKNOWN")
130
+ lines.append(
131
+ f"{info.get('away_team')} at {info.get('home_team')} [{status}] {_when(info)}"
132
+ )
133
+
134
+ score = game.get("score")
135
+ if score:
136
+ lines.extend(_score_lines(score))
137
+
138
+ players = game.get("players")
139
+ if players:
140
+ lines.append(f" player stats for {len(players)} player(s)")
141
+ lines.append("")
142
+
143
+ lines.append(
144
+ "A named total (half_time, full_time) stays null until that period is "
145
+ "complete. For a live running total, sum the by_period values."
146
+ )
147
+ return "\n".join(lines)
148
+
149
+
150
+ def _score_lines(score: Mapping[str, Any]) -> list[str]:
151
+ """Scores exactly as the sport reports them.
152
+
153
+ Scoring fields differ by sport, AFL counting goals, behinds and points
154
+ where MLB counts runs and hits, so the field names are passed through
155
+ rather than mapped onto a guessed "the score". Nothing here needs to know
156
+ which sport it is looking at.
157
+ """
158
+ lines = []
159
+
160
+ for side in ("away", "home"):
161
+ team = score.get(side) or {}
162
+ stats = _stats(team)
163
+ if stats:
164
+ lines.append(f" {team.get('team', side)}: {stats}")
165
+
166
+ totals = score.get("totals") or {}
167
+ for key in ("full_time", "half_time", "first_5_innings"):
168
+ value = totals.get(key)
169
+ if isinstance(value, dict) and value:
170
+ lines.append(f" {key} (both teams): {_stats(value)}")
171
+
172
+ state = score.get("period_state") or []
173
+ if state:
174
+ done = sum(1 for period in state if period.get("completed"))
175
+ lines.append(f" periods: {done} of {len(state)} complete")
176
+
177
+ return lines
178
+
179
+
180
+ def _stats(values: Mapping[str, Any]) -> str:
181
+ return ", ".join(f"{key} {value}" for key, value in values.items() if key != "team")
182
+
183
+
184
+ def _by_market(entry: Mapping[str, Any]) -> dict[str, dict[Selection, list[tuple[float, str]]]]:
185
+ """Invert bookmaker -> market -> outcome into market -> selection -> prices."""
186
+ markets: dict[str, dict[Selection, list[tuple[float, str]]]] = {}
187
+
188
+ for book in entry.get("bookmakers", []):
189
+ for market in book.get("markets", []):
190
+ key = market.get("key", "unknown")
191
+ for outcome in market.get("outcomes", []):
192
+ price = outcome.get("price")
193
+ if price is None:
194
+ continue
195
+ name = outcome.get("player_name") or outcome.get("name", "")
196
+ selection: Selection = (name, outcome.get("point"))
197
+ markets.setdefault(key, {}).setdefault(selection, []).append(
198
+ (price, book.get("name", "?"))
199
+ )
200
+
201
+ return markets
202
+
203
+
204
+ def _when(game: Mapping[str, Any]) -> str:
205
+ """Timestamps are naive UTC with no offset, so the zone is stated explicitly."""
206
+ raw = game.get("commence_time") or game.get("start_time")
207
+ if not raw:
208
+ return ""
209
+ return f"({raw.replace('T', ' ')} UTC)"
@@ -0,0 +1,367 @@
1
+ """The MCP server and its tools.
2
+
3
+ Five tools rather than one per endpoint. Every extra tool is another thing to
4
+ pick wrongly, and a wrong pick here costs credits.
5
+
6
+ Each tool ends with what it spent and what is left. Credits are the scarce
7
+ resource, the free tier is 250 for the life of the account, and a model that
8
+ cannot see the meter has no reason to slow down.
9
+ """
10
+
11
+ import os
12
+ from collections.abc import Sequence
13
+
14
+ from mcp.server import MCPServer
15
+ from rapidoddsapi import RapidOddsAPI
16
+ from rapidoddsapi import find_arbitrage as arb
17
+ from rapidoddsapi import find_value_bets as value
18
+ from rapidoddsapi.exceptions import (
19
+ APIError,
20
+ AuthenticationError,
21
+ InsufficientCreditsError,
22
+ RapidOddsAPIError,
23
+ ValidationError,
24
+ )
25
+ from rapidoddsapi.types import OddsResponse, Usage
26
+
27
+ from . import __version__
28
+ from .defaults import (
29
+ SHARP_BOOKMAKER,
30
+ default_bookmakers,
31
+ wide_bookmakers,
32
+ with_sharp,
33
+ )
34
+ from .formatting import (
35
+ credit_line,
36
+ format_arbitrage,
37
+ format_odds,
38
+ format_results,
39
+ format_value_bets,
40
+ )
41
+
42
+ API_KEY_ENV = "RAPIDODDSAPI_API_KEY"
43
+
44
+ INSTRUCTIONS = """
45
+ Odds, live scores, arbitrage and value bets from RapidOddsAPI.
46
+
47
+ Credits are charged per request and the free tier is 250 for the lifetime of
48
+ the account, with no monthly reset. Every response reports what it cost and
49
+ what is left.
50
+
51
+ Two rules that keep the cost down:
52
+ - A sport is always required. There is no way to ask for every sport at once.
53
+ - Leave bookmakers unset unless you need specific ones. The default is five,
54
+ which is the cheapest useful request. Cost multiplies with both the number
55
+ of market types and the number of bookmakers.
56
+
57
+ list_sports is free. Call it first when unsure of a sport id or a market type.
58
+ """.strip()
59
+
60
+ server = MCPServer(
61
+ name="rapidoddsapi",
62
+ version=__version__,
63
+ instructions=INSTRUCTIONS,
64
+ )
65
+
66
+ _client: RapidOddsAPI | None = None
67
+
68
+
69
+ def get_client() -> RapidOddsAPI:
70
+ """One client for the process, built on first use.
71
+
72
+ Built lazily so a missing key surfaces as a readable tool error rather than
73
+ the server dying at startup, where nothing would explain why it vanished.
74
+ """
75
+ global _client
76
+ if _client is None:
77
+ key = os.environ.get(API_KEY_ENV, "").strip()
78
+ if not key:
79
+ raise AuthenticationError(
80
+ f"No API key. Set {API_KEY_ENV} to your key from "
81
+ "https://rapidoddsapi.com/dashboard (it starts with 'oa_')."
82
+ )
83
+ _client = RapidOddsAPI(api_key=key)
84
+ return _client
85
+
86
+
87
+ def _usage() -> Usage | None:
88
+ """Current balance, or None if the lookup fails.
89
+
90
+ A failed balance check must not lose the answer the tool already fetched.
91
+ """
92
+ try:
93
+ return get_client().get_usage()
94
+ except RapidOddsAPIError:
95
+ return None
96
+
97
+
98
+ def _explain(exc: Exception) -> str:
99
+ """Turn an SDK exception into something a model can act on."""
100
+ if isinstance(exc, InsufficientCreditsError):
101
+ left = exc.credits_remaining
102
+ tail = f" {left} credits remain." if left is not None else ""
103
+ return (
104
+ f"Out of credits.{tail} Stop making paid requests and tell the user "
105
+ f"they need to top up at https://rapidoddsapi.com/dashboard."
106
+ )
107
+ if isinstance(exc, AuthenticationError):
108
+ return str(exc)
109
+ if isinstance(exc, ValidationError):
110
+ return f"Invalid request: {exc}"
111
+ if isinstance(exc, APIError):
112
+ return f"API error: {exc}"
113
+ return f"Request failed: {exc}"
114
+
115
+
116
+ def _fetch_odds(
117
+ sport: str, market_types: Sequence[str], bookmakers: Sequence[str]
118
+ ) -> tuple[OddsResponse, int]:
119
+ """Fetch odds and report the exact cost.
120
+
121
+ Cost comes from the SDK's own tally rather than being recalculated here, so
122
+ it stays right, including the rule that an empty response is free.
123
+ """
124
+ client = get_client()
125
+ before = client.credits_used
126
+ response = client.get_odds(sport, list(market_types), list(bookmakers))
127
+ return response, client.credits_used - before
128
+
129
+
130
+ @server.tool()
131
+ def list_sports(sport: str | None = None) -> str:
132
+ """List the sports available, or one sport's market types.
133
+
134
+ Costs 0 credits, so call it freely. Use it before get_odds whenever the
135
+ sport id or the market type is not certain, since a guessed market type
136
+ returns nothing and a guessed sport id is an error.
137
+
138
+ With no argument: every sport id, plus which of them have live scores.
139
+ With a sport: that sport's market types, grouped into game, team and
140
+ player_props. Any of those keys is valid as a get_odds market_type.
141
+
142
+ A sport being listed means the id is accepted, not that games are on right
143
+ now. Out of season returns an empty result, which costs nothing.
144
+ """
145
+ try:
146
+ client = get_client()
147
+
148
+ if sport is not None:
149
+ info = client.get_sport(sport)
150
+ markets = info.get("markets")
151
+ lines = [f"{info['name']} ({info['id']}) market types:", ""]
152
+ if markets is not None:
153
+ groups = (
154
+ ("game", markets["game"]),
155
+ ("team", markets["team"]),
156
+ ("player_props", markets["player_props"]),
157
+ )
158
+ for group, keys in groups:
159
+ if keys:
160
+ lines.append(f"{group} ({len(keys)}):")
161
+ lines.extend(f" {key}" for key in keys)
162
+ lines.append("")
163
+ lines.append(credit_line(0, _usage()))
164
+ return "\n".join(lines)
165
+
166
+ sports = client.list_sports()
167
+ with_results = {s["id"] for s in client.list_results_sports()}
168
+
169
+ lines = [f"{len(sports)} sports:", ""]
170
+ for entry in sports:
171
+ mark = " (live scores available)" if entry["id"] in with_results else ""
172
+ lines.append(f" {entry['id']:<16} {entry['name']}{mark}")
173
+ lines += [
174
+ "",
175
+ "Pass a sport to this tool to see its market types.",
176
+ credit_line(0, _usage()),
177
+ ]
178
+ return "\n".join(lines)
179
+ except Exception as exc:
180
+ return _explain(exc)
181
+
182
+
183
+ @server.tool()
184
+ def get_odds(
185
+ sport: str,
186
+ market_types: list[str] | None = None,
187
+ bookmakers: list[str] | None = None,
188
+ ) -> str:
189
+ """Current bookmaker odds for one sport.
190
+
191
+ sport is required and must be an id from list_sports. There is no option
192
+ for every sport at once.
193
+
194
+ Cost: number of market types x ceil(number of bookmakers / 5) credits,
195
+ charged only when games come back. The defaults, one market across five
196
+ bookmakers, cost 1 credit. Both arguments multiply, so nine market types
197
+ across eighteen bookmakers is 36 credits. Widen only when asked to.
198
+
199
+ market_types defaults to head_to_head, the plain winner market. Soccer has
200
+ no head_to_head because of the draw, so use head_to_head_3_way or
201
+ draw_no_bet there. Get exact keys from list_sports(sport).
202
+
203
+ bookmakers defaults to five that cover the sport's region. Names are odds
204
+ feeds, not brands: "Ladbrokes" covers Neds, "Betmakers" covers the 26
205
+ brands on that feed. A brand name that is not a feed returns nothing.
206
+ """
207
+ markets = market_types or ["head_to_head"]
208
+ books = bookmakers or default_bookmakers(sport)
209
+
210
+ try:
211
+ response, cost = _fetch_odds(sport, markets, books)
212
+ except Exception as exc:
213
+ return _explain(exc)
214
+
215
+ body = format_odds(response, books)
216
+ if not body:
217
+ return (
218
+ f"No games for {sport} from {', '.join(books)} "
219
+ f"on {', '.join(markets)}.\n"
220
+ f"Nothing was charged, since empty responses are free. The season "
221
+ f"may be over, or these bookmakers may not price this market. "
222
+ f"Check list_sports({sport!r}) for valid market types before "
223
+ f"retrying.\n" + credit_line(cost, _usage())
224
+ )
225
+
226
+ return f"{body}\n\n{credit_line(cost, _usage())}"
227
+
228
+
229
+ @server.tool()
230
+ def get_results(
231
+ sport: str,
232
+ status: str = "all",
233
+ include: list[str] | None = None,
234
+ ) -> str:
235
+ """Live scores and player stats for one sport.
236
+
237
+ Costs 1 credit, charged only when games come back, whatever the filters.
238
+
239
+ Results cover fewer sports than odds do. list_sports marks which ones have
240
+ them; asking for a sport without results coverage returns nothing.
241
+
242
+ status: all (default), live, concluded or upcoming.
243
+ include: scores, players, or both (default). A typo is rejected.
244
+
245
+ A named total such as full_time stays null until that period is complete,
246
+ so nothing settles early. Sum by_period for a live running total.
247
+ """
248
+ try:
249
+ client = get_client()
250
+ before = client.credits_used
251
+ response = client.get_results(
252
+ sport, status=status, include=include or ["scores", "players"]
253
+ )
254
+ cost = client.credits_used - before
255
+ except Exception as exc:
256
+ return _explain(exc)
257
+
258
+ body = format_results(response)
259
+ if not body:
260
+ return (
261
+ f"No {status} games for {sport}. Nothing was charged, since empty "
262
+ f"responses are free. Results cover fewer sports than odds do, so "
263
+ f"check list_sports() for which have live scores.\n"
264
+ + credit_line(cost, _usage())
265
+ )
266
+
267
+ return f"{body}\n\n{credit_line(cost, _usage())}"
268
+
269
+
270
+ @server.tool()
271
+ def find_arbitrage(
272
+ sport: str,
273
+ market: str = "head_to_head",
274
+ bookmakers: list[str] | None = None,
275
+ min_profit: float = 1.0,
276
+ stake: float = 100.0,
277
+ ) -> str:
278
+ """Find bets where backing both sides at different bookmakers locks in profit.
279
+
280
+ Fetches odds first, so it costs the same as get_odds:
281
+ ceil(number of bookmakers / 5) credits for the single market. It defaults
282
+ to ten bookmakers, 2 credits, because an arbitrage only exists when books
283
+ disagree and five rarely spread far enough.
284
+
285
+ Only two-way markets with no line work: head_to_head, its period variants
286
+ such as head_to_head_1st_half, and soccer's draw_no_bet. Totals, spreads,
287
+ player props and three-way markets are rejected with an explanation rather
288
+ than silently returning nothing.
289
+
290
+ min_profit is a percentage, default 1.0. Below roughly 1 percent an edge
291
+ usually disappears while the second leg is being placed.
292
+ """
293
+ books = bookmakers or wide_bookmakers(sport)
294
+
295
+ try:
296
+ response, cost = _fetch_odds(sport, [market], books)
297
+ found = arb(response, market=market, stake=stake, min_profit=min_profit)
298
+ except Exception as exc:
299
+ return _explain(exc)
300
+
301
+ body = format_arbitrage(found, stake)
302
+ if not body:
303
+ return (
304
+ f"No arbitrage on {market} for {sport} above {min_profit}% "
305
+ f"across {len(books)} bookmakers.\n"
306
+ f"This is the normal result. Arbitrage is rare and short lived.\n"
307
+ + credit_line(cost, _usage())
308
+ )
309
+
310
+ return f"{body}\n{credit_line(cost, _usage())}"
311
+
312
+
313
+ @server.tool()
314
+ def find_value_bets(
315
+ sport: str,
316
+ market: str = "head_to_head",
317
+ bookmakers: list[str] | None = None,
318
+ min_edge: float = 2.0,
319
+ sharp: str = SHARP_BOOKMAKER,
320
+ ) -> str:
321
+ """Find prices that beat a sharp bookmaker's fair value.
322
+
323
+ A sharp book runs thin margins and moves fast, so its prices track true
324
+ probability. Stripping its margin gives a fair price, and any book paying
325
+ more than that is positive expected value.
326
+
327
+ Fetches odds first, so it costs the same as get_odds:
328
+ ceil(number of bookmakers / 5) credits for the single market. Defaults to
329
+ ten bookmakers, 2 credits. The sharp book is added automatically if it is
330
+ not in the list, since the calculation is impossible without it.
331
+
332
+ Same market limits as find_arbitrage: two-way, no line. head_to_head, its
333
+ period variants, and soccer's draw_no_bet.
334
+
335
+ min_edge is a percentage, default 2.0. Smaller edges are usually inside the
336
+ error of the fair price rather than real value.
337
+ """
338
+ # Seeded into the default spread so it stays at ten books and two credits.
339
+ # An explicit list is respected as given, with the sharp book appended only
340
+ # because the edge cannot be worked out without it.
341
+ books = (
342
+ list(with_sharp(bookmakers))
343
+ if bookmakers
344
+ else list(wide_bookmakers(sport, must_include=(sharp,)))
345
+ )
346
+
347
+ try:
348
+ response, cost = _fetch_odds(sport, [market], books)
349
+ found = value(response, sharp=sharp, market=market, min_edge=min_edge)
350
+ except Exception as exc:
351
+ return _explain(exc)
352
+
353
+ body = format_value_bets(found, sharp)
354
+ if not body:
355
+ return (
356
+ f"No value on {market} for {sport} above {min_edge}% against "
357
+ f"{sharp}.\n"
358
+ f"If {sharp} does not price this sport there is nothing to compare "
359
+ f"against, which looks the same as finding nothing.\n"
360
+ + credit_line(cost, _usage())
361
+ )
362
+
363
+ return f"{body}\n{credit_line(cost, _usage())}"
364
+
365
+
366
+ def main() -> None:
367
+ server.run()
@@ -0,0 +1,136 @@
1
+ Metadata-Version: 2.4
2
+ Name: rapidoddsapi-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for RapidOddsAPI: bookmaker odds, live scores, arbitrage and value bets.
5
+ Project-URL: Homepage, https://rapidoddsapi.com
6
+ Project-URL: Documentation, https://rapidoddsapi.com/docs
7
+ Project-URL: Repository, https://github.com/rapidoddsapi/rapidoddsapi-mcp
8
+ Author-email: RapidOddsAPI <support@rapidoddsapi.com>
9
+ License: MIT
10
+ License-File: LICENSE
11
+ Keywords: arbitrage,betting,bookmaker,mcp,odds,sports
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.10
17
+ Classifier: Programming Language :: Python :: 3.11
18
+ Classifier: Programming Language :: Python :: 3.12
19
+ Classifier: Programming Language :: Python :: 3.13
20
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
21
+ Requires-Python: >=3.10
22
+ Requires-Dist: mcp>=2.0.0
23
+ Requires-Dist: rapidoddsapi>=0.2.0
24
+ Provides-Extra: dev
25
+ Requires-Dist: mypy>=1.11; extra == 'dev'
26
+ Requires-Dist: pytest>=8.0; extra == 'dev'
27
+ Requires-Dist: ruff>=0.6; extra == 'dev'
28
+ Description-Content-Type: text/markdown
29
+
30
+ # rapidoddsapi-mcp
31
+
32
+ MCP server for [RapidOddsAPI](https://rapidoddsapi.com). Gives an AI assistant
33
+ bookmaker odds, live scores, arbitrage and value bets.
34
+
35
+ Built on the official [`rapidoddsapi`](https://pypi.org/project/rapidoddsapi)
36
+ Python SDK.
37
+
38
+ ## Setup
39
+
40
+ You need an API key from the [dashboard](https://rapidoddsapi.com/dashboard).
41
+ Keys start with `oa_`.
42
+
43
+ ### Claude Desktop
44
+
45
+ Add this to `claude_desktop_config.json`:
46
+
47
+ ```json
48
+ {
49
+ "mcpServers": {
50
+ "rapidoddsapi": {
51
+ "command": "uvx",
52
+ "args": ["rapidoddsapi-mcp"],
53
+ "env": {
54
+ "RAPIDODDSAPI_API_KEY": "oa_your_api_key_here"
55
+ }
56
+ }
57
+ }
58
+ }
59
+ ```
60
+
61
+ The config file lives at `~/Library/Application Support/Claude/` on macOS and
62
+ `%APPDATA%\Claude\` on Windows. Restart Claude Desktop after editing it.
63
+
64
+ ### Anything else that speaks MCP
65
+
66
+ ```bash
67
+ RAPIDODDSAPI_API_KEY=oa_your_api_key_here uvx rapidoddsapi-mcp
68
+ ```
69
+
70
+ It speaks stdio.
71
+
72
+ ## Tools
73
+
74
+ | Tool | Credits |
75
+ |---|---|
76
+ | `list_sports(sport=)` | 0 |
77
+ | `get_odds(sport, market_types=, bookmakers=)` | `market_types x ceil(bookmakers / 5)` |
78
+ | `get_results(sport, status=, include=)` | 1 |
79
+ | `find_arbitrage(sport, market=, bookmakers=, min_profit=, stake=)` | `ceil(bookmakers / 5)` |
80
+ | `find_value_bets(sport, market=, bookmakers=, min_edge=, sharp=)` | `ceil(bookmakers / 5)` |
81
+
82
+ Credits are charged only when games come back, so a query that matches nothing
83
+ is free. Every response ends with what it cost and what is left.
84
+
85
+ ## Credits
86
+
87
+ The free tier is 250 credits for the life of the account, with no monthly
88
+ reset, so the defaults are deliberately narrow:
89
+
90
+ - A sport is always required. There is no way to request every sport at once.
91
+ - Bookmakers default to five, one credit group, chosen for the sport's region.
92
+ - Market types default to one.
93
+
94
+ That makes a typical question cost 1 credit. Both arguments multiply, so asking
95
+ for nine market types across eighteen bookmakers is 36. The tool descriptions
96
+ say so, which is what keeps the model from doing it uninvited.
97
+
98
+ `find_arbitrage` and `find_value_bets` default to ten bookmakers, 2 credits,
99
+ because both need books that disagree and five rarely spread far enough.
100
+
101
+ ## Markets
102
+
103
+ `find_arbitrage` and `find_value_bets` handle two-way markets with no line:
104
+ `head_to_head`, its period variants, and soccer's `draw_no_bet`. Totals,
105
+ spreads, player props and three-way markets return an error explaining why
106
+ rather than an empty list, since "nothing found" would read as "no
107
+ opportunities".
108
+
109
+ Market keys vary by sport. `list_sports(sport)` returns the valid ones and
110
+ costs nothing.
111
+
112
+ ## Bookmakers
113
+
114
+ Names are odds feeds, not brands. Many brands share one feed and quote
115
+ identical prices, so `Ladbrokes` covers Neds and `Betmakers` covers the 26
116
+ brands running on it. A brand name that is not a feed returns nothing.
117
+
118
+ ## Development
119
+
120
+ ```bash
121
+ pip install -e ".[dev]"
122
+ pytest
123
+ ruff check .
124
+ mypy src/rapidoddsapi_mcp
125
+ ```
126
+
127
+ ## Links
128
+
129
+ - [RapidOddsAPI](https://rapidoddsapi.com)
130
+ - [Documentation](https://rapidoddsapi.com/docs)
131
+ - [Coverage: sports, bookmakers, market keys](https://rapidoddsapi.com/coverage)
132
+ - [Python SDK](https://github.com/rapidoddsapi/rapidoddsapi-python)
133
+
134
+ ## License
135
+
136
+ MIT
@@ -0,0 +1,10 @@
1
+ rapidoddsapi_mcp/__init__.py,sha256=EnEtnNf9KuIrLsR8IWEHymPNNnh6MItiWGieCHDIqDg,206
2
+ rapidoddsapi_mcp/__main__.py,sha256=9it1my_mM7xBpDh79QSi7FAvZD3Vki3GQFPJIDZw_zs,64
3
+ rapidoddsapi_mcp/defaults.py,sha256=z5ccx0ik-M8iuXwaJ4g-ldpazu2IEtSVSuuZRgttGW4,3049
4
+ rapidoddsapi_mcp/formatting.py,sha256=Ywk79nPqR4886pJrTKrgTZrtjLF1Lvcr1PhEv0v4Lgw,7580
5
+ rapidoddsapi_mcp/server.py,sha256=bhHyV-rw00UykUAP7DnwHQfnPB8tp8s9ra70DtBzpnc,12956
6
+ rapidoddsapi_mcp-0.1.0.dist-info/METADATA,sha256=bSCZDaoqcdAGayXHdmf77YCG2Od0QWw-5LBw2X0EKEs,4370
7
+ rapidoddsapi_mcp-0.1.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
8
+ rapidoddsapi_mcp-0.1.0.dist-info/entry_points.txt,sha256=cWhhlve3T7qBglGqj-LwdYweBJLNMC6CzmgmJVU8XX0,66
9
+ rapidoddsapi_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=Ow_APIC3h6QJhx-Llq4rTU-hZnBIbVlB9zmmkCFbC28,1069
10
+ rapidoddsapi_mcp-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.31.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ rapidoddsapi-mcp = rapidoddsapi_mcp.server:main
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 RapidOddsAPI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.