rapidoddsapi-mcp 0.1.0__tar.gz

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,50 @@
1
+ # Byte-compiled / cache
2
+ __pycache__/
3
+ *.py[cod]
4
+ *$py.class
5
+
6
+ # Distribution / packaging
7
+ build/
8
+ dist/
9
+ *.egg-info/
10
+ *.egg
11
+ .eggs/
12
+
13
+ # Virtual environments
14
+ .venv/
15
+ venv/
16
+ env/
17
+ ENV/
18
+
19
+ # Testing / coverage
20
+ .pytest_cache/
21
+ .tox/
22
+ .nox/
23
+ .coverage
24
+ .coverage.*
25
+ htmlcov/
26
+ coverage.xml
27
+
28
+ # Type checkers / linters
29
+ .mypy_cache/
30
+ .ruff_cache/
31
+ .pytype/
32
+
33
+ # Secrets
34
+ .env
35
+ .env.*
36
+ !.env.example
37
+
38
+ # Local scratch scripts and notes
39
+ live_check.py
40
+ try_*.py
41
+ notes.txt
42
+
43
+ # Editors
44
+ .vscode/
45
+ .idea/
46
+ *.swp
47
+
48
+ # OS
49
+ .DS_Store
50
+ Thumbs.db
@@ -0,0 +1,15 @@
1
+ # Changelog
2
+
3
+ Notable changes to this package. Versions follow [semantic versioning](https://semver.org).
4
+
5
+ ## 0.1.0
6
+
7
+ First release.
8
+
9
+ - Five tools: `list_sports`, `get_odds`, `get_results`, `find_arbitrage`,
10
+ `find_value_bets`
11
+ - Every response reports what it cost and the credits remaining
12
+ - A sport is always required, and bookmakers default to five, so a vague
13
+ question costs 1 credit rather than tens
14
+ - Built on the `rapidoddsapi` SDK, which needs the API at v1.1.0 or later for
15
+ the sport directory and balance lookups
@@ -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.
@@ -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,107 @@
1
+ # rapidoddsapi-mcp
2
+
3
+ MCP server for [RapidOddsAPI](https://rapidoddsapi.com). Gives an AI assistant
4
+ bookmaker odds, live scores, arbitrage and value bets.
5
+
6
+ Built on the official [`rapidoddsapi`](https://pypi.org/project/rapidoddsapi)
7
+ Python SDK.
8
+
9
+ ## Setup
10
+
11
+ You need an API key from the [dashboard](https://rapidoddsapi.com/dashboard).
12
+ Keys start with `oa_`.
13
+
14
+ ### Claude Desktop
15
+
16
+ Add this to `claude_desktop_config.json`:
17
+
18
+ ```json
19
+ {
20
+ "mcpServers": {
21
+ "rapidoddsapi": {
22
+ "command": "uvx",
23
+ "args": ["rapidoddsapi-mcp"],
24
+ "env": {
25
+ "RAPIDODDSAPI_API_KEY": "oa_your_api_key_here"
26
+ }
27
+ }
28
+ }
29
+ }
30
+ ```
31
+
32
+ The config file lives at `~/Library/Application Support/Claude/` on macOS and
33
+ `%APPDATA%\Claude\` on Windows. Restart Claude Desktop after editing it.
34
+
35
+ ### Anything else that speaks MCP
36
+
37
+ ```bash
38
+ RAPIDODDSAPI_API_KEY=oa_your_api_key_here uvx rapidoddsapi-mcp
39
+ ```
40
+
41
+ It speaks stdio.
42
+
43
+ ## Tools
44
+
45
+ | Tool | Credits |
46
+ |---|---|
47
+ | `list_sports(sport=)` | 0 |
48
+ | `get_odds(sport, market_types=, bookmakers=)` | `market_types x ceil(bookmakers / 5)` |
49
+ | `get_results(sport, status=, include=)` | 1 |
50
+ | `find_arbitrage(sport, market=, bookmakers=, min_profit=, stake=)` | `ceil(bookmakers / 5)` |
51
+ | `find_value_bets(sport, market=, bookmakers=, min_edge=, sharp=)` | `ceil(bookmakers / 5)` |
52
+
53
+ Credits are charged only when games come back, so a query that matches nothing
54
+ is free. Every response ends with what it cost and what is left.
55
+
56
+ ## Credits
57
+
58
+ The free tier is 250 credits for the life of the account, with no monthly
59
+ reset, so the defaults are deliberately narrow:
60
+
61
+ - A sport is always required. There is no way to request every sport at once.
62
+ - Bookmakers default to five, one credit group, chosen for the sport's region.
63
+ - Market types default to one.
64
+
65
+ That makes a typical question cost 1 credit. Both arguments multiply, so asking
66
+ for nine market types across eighteen bookmakers is 36. The tool descriptions
67
+ say so, which is what keeps the model from doing it uninvited.
68
+
69
+ `find_arbitrage` and `find_value_bets` default to ten bookmakers, 2 credits,
70
+ because both need books that disagree and five rarely spread far enough.
71
+
72
+ ## Markets
73
+
74
+ `find_arbitrage` and `find_value_bets` handle two-way markets with no line:
75
+ `head_to_head`, its period variants, and soccer's `draw_no_bet`. Totals,
76
+ spreads, player props and three-way markets return an error explaining why
77
+ rather than an empty list, since "nothing found" would read as "no
78
+ opportunities".
79
+
80
+ Market keys vary by sport. `list_sports(sport)` returns the valid ones and
81
+ costs nothing.
82
+
83
+ ## Bookmakers
84
+
85
+ Names are odds feeds, not brands. Many brands share one feed and quote
86
+ identical prices, so `Ladbrokes` covers Neds and `Betmakers` covers the 26
87
+ brands running on it. A brand name that is not a feed returns nothing.
88
+
89
+ ## Development
90
+
91
+ ```bash
92
+ pip install -e ".[dev]"
93
+ pytest
94
+ ruff check .
95
+ mypy src/rapidoddsapi_mcp
96
+ ```
97
+
98
+ ## Links
99
+
100
+ - [RapidOddsAPI](https://rapidoddsapi.com)
101
+ - [Documentation](https://rapidoddsapi.com/docs)
102
+ - [Coverage: sports, bookmakers, market keys](https://rapidoddsapi.com/coverage)
103
+ - [Python SDK](https://github.com/rapidoddsapi/rapidoddsapi-python)
104
+
105
+ ## License
106
+
107
+ MIT
@@ -0,0 +1,59 @@
1
+ [build-system]
2
+ requires = ["hatchling"]
3
+ build-backend = "hatchling.build"
4
+
5
+ [project]
6
+ name = "rapidoddsapi-mcp"
7
+ dynamic = ["version"]
8
+ description = "MCP server for RapidOddsAPI: bookmaker odds, live scores, arbitrage and value bets."
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = { text = "MIT" }
12
+ authors = [{ name = "RapidOddsAPI", email = "support@rapidoddsapi.com" }]
13
+ keywords = ["mcp", "odds", "betting", "bookmaker", "arbitrage", "sports"]
14
+ classifiers = [
15
+ "Development Status :: 4 - Beta",
16
+ "Intended Audience :: Developers",
17
+ "License :: OSI Approved :: MIT License",
18
+ "Programming Language :: Python :: 3",
19
+ "Programming Language :: Python :: 3.10",
20
+ "Programming Language :: Python :: 3.11",
21
+ "Programming Language :: Python :: 3.12",
22
+ "Programming Language :: Python :: 3.13",
23
+ "Topic :: Software Development :: Libraries :: Python Modules",
24
+ ]
25
+ dependencies = [
26
+ "mcp>=2.0.0",
27
+ "rapidoddsapi>=0.2.0",
28
+ ]
29
+
30
+ [project.optional-dependencies]
31
+ dev = ["pytest>=8.0", "ruff>=0.6", "mypy>=1.11"]
32
+
33
+ [project.scripts]
34
+ rapidoddsapi-mcp = "rapidoddsapi_mcp.server:main"
35
+
36
+ [project.urls]
37
+ Homepage = "https://rapidoddsapi.com"
38
+ Documentation = "https://rapidoddsapi.com/docs"
39
+ Repository = "https://github.com/rapidoddsapi/rapidoddsapi-mcp"
40
+
41
+ [tool.hatch.version]
42
+ path = "src/rapidoddsapi_mcp/__init__.py"
43
+
44
+ [tool.hatch.build.targets.wheel]
45
+ packages = ["src/rapidoddsapi_mcp"]
46
+
47
+ [tool.ruff]
48
+ line-length = 100
49
+ src = ["src", "tests"]
50
+
51
+ [tool.ruff.lint]
52
+ select = ["E", "F", "I", "UP", "B"]
53
+
54
+ [tool.mypy]
55
+ python_version = "3.10"
56
+ strict = true
57
+
58
+ [tool.pytest.ini_options]
59
+ testpaths = ["tests"]
@@ -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]