Purpose
TheRundown Data MCP is the official Model Context Protocol (MCP) server provided by TheRundown, used to let AI clients access TheRundown's sports data product API in a read-only manner, including sports events, markets, leagues, events, futures, and public main-line odds. This repository is the official source repository; aigeon-ai/therundown is an unofficial version.
Main Capabilities
The currently deployed version 0.3.0 provides six read-only convenience tools, including list_markets and list_futures, among others. list_markets supports catalog discovery and can also discover available markets by sport_id and date; date-based discovery rejects live because that endpoint does not classify live markets. Event queries always use main_line=true, hide_closed=true, and include=all_periods. list_futures is an Ultra+ contest endpoint with scoped defaults [1141] and [19,23], uses opaque cursor pagination, and returns public schedule/settlement fields as well as open main-line odds for each league (excluding line IDs). Event tools with dates default to markets [1,2,3] and leagues [19,23]; live markets [41,42,43] must be passed explicitly. Retired league 27 is rejected and excluded from discovery. The 0.4.0 source candidate registers 75 public REST operation tools, four bounded real WebSocket capture tools, and six existing convenience tools, using the official MCP SDK and Node.js 22+. COVERAGE.md lists the exact routes, aliases, retired/private exclusions, and transport limitations. Each WebSocket capture opens a real upstream WebSocket, observes for at most five seconds/50 messages/256 KiB, and then closes; it is not a continuous background data stream.
Usage
Hosted account connection addresses are https://mcp.therundown.io/oauth/mcp；旧版 / and /mcp accept a Product API key passed in the authentication header. ChatGPT uses Streamable HTTP. Anonymous metadata and ping do not call the Product API. Every data tool requires local key authentication or a connected account on the OAuth route. Running locally requires checking out the source from the repository and using Node.js 22+. You can also download the versioned source package (the official ZIP is 41,072 bytes, SHA-256 is cb0a0841aa040f049ffddec5b5fa2436cb9de721a30a3bd53270132db7204025), verify the checksum, and extract it. The historical source ZIP is still 0.2.3, does not include this candidate, and only supports stdio; npm start will not start the HTTP adapter. There is no published npm package. Manual local configuration for Claude Desktop: where supported, add the configuration to claude_desktop_config.json and restart the client, using absolute Node 22+ and server paths; this source ZIP is not a .mcpb desktop extension. Cursor uses the global ~/.cursor/mcp.json, and ensure the key is available in the environment where Cursor is started. The server reads THERUNDOWN_API_KEY from the process environment and sends it only as X-TheRundown-Key; the key is never accepted as a tool parameter. stdout contains only MCP protocol messages. Without a key, the process can still be used for MCP metadata discovery and returns a sanitized missing_credentials error on Product tool calls, without making network requests.
Applicable Scenarios
Suitable for scenarios that need to integrate TheRundown sports data into AI clients (such as ChatGPT, Claude Desktop, Cursor), for querying read-only data such as events, markets, odds, and futures. The current Build with AI rules and first-conversation instructions can be read via the MCP resource therundown://brief; initialization also returns the same instructions, and neither calls the Product API.
Limitations
Usage, API plan latency, and permissions apply to each request. CurRecords, dated markets, events, and main board pages are paginated locally, so each page re-fetches a snapshot and is metered separately. list_futures uses an API upstream opaque cursor and page limit; each cursor page is still a metered request, and when has_more is true it is only a partial contest list. Results expose the safe source URL, retrieval timestamp, API usage headers, and each price's updated_at; the retrieval timestamp cannot prove that a price is fresh. HTTP failures return status, plan, missing_entitlement, required_plan, retry_after (seconds), remaining_points, monthly_remaining_points, and limit_reason, along with the safe source URL, retrieval time, and usage headers. Fields remain null when the API does not provide an identifiable value. The server does not guess the current plan from a rejected feature. Raw upstream error bodies are never returned, and errors do not trigger automatic retries. Empty successful results preserve the normal data shape and add empty along with a code, explanation, and request scope. Dated results report the sport, date, and date boundary offset (zero for UTC); pages beyond existing results are identified separately from empty lists. Empty odds cannot prove that coverage is missing. The free tier includes delayed pregame odds and excludes live odds, props/alternate lines, and history; a source catalog row does not grant access to it. npm test runs offline. To inspect actual Product API data, privately set THERUNDOWN_API_KEY and run npm run smoke; by default it checks MLB pregame [1,2,3] and leagues [19,23]. An eligible key can set THERUNDOWN_SMOKE_LIVE=1 to request live [41,42,43]; THERUNDOWN_SMOKE_DATE=YYYY-MM-DD and THERUNDOWN_SMOKE_SPORT_ID select the date range. A bounded Ultra+ contest check requires setting THERUNDOWN_SMOKE_FUTURES=1 and a sport (such as 40 for PGA, 41 for Formula 1), and requests only market 1141 and leagues 19,23. The check has a 60-second deadline, validates the reviewed source tool inventory, and reports the UTC check time,scope, selected event IDs, source URLs, usage, and counts. It requires status: "ok", a complete source tool inventory, and positive event/main board counts. Empty data is inconclusive and ends with exit code 2. These requests are opt-in and metered. The documentation MCP is located at https://docs.therundown.io/mcp，不能返回 Product prices. See the setup guide, DESIGN.md, the authentication and billing documentation, as well as the OpenAPI specification, sports catalog, markets catalog, leagues catalog, TheRundown llms.txt, and documentation llms.txt for the current public contract and IDs.
