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.
- rapidoddsapi_mcp/__init__.py +9 -0
- rapidoddsapi_mcp/__main__.py +4 -0
- rapidoddsapi_mcp/defaults.py +85 -0
- rapidoddsapi_mcp/formatting.py +209 -0
- rapidoddsapi_mcp/server.py +367 -0
- rapidoddsapi_mcp-0.1.0.dist-info/METADATA +136 -0
- rapidoddsapi_mcp-0.1.0.dist-info/RECORD +10 -0
- rapidoddsapi_mcp-0.1.0.dist-info/WHEEL +4 -0
- rapidoddsapi_mcp-0.1.0.dist-info/entry_points.txt +2 -0
- rapidoddsapi_mcp-0.1.0.dist-info/licenses/LICENSE +21 -0
|
@@ -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,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.
|