livetennisapi-mcp
MCP server that gives LLM clients read-only access to Live Tennis API data, from live scores to historical archives and analytics.
Fetch live matches, upcoming matches, fixtures, match detail, and lowest-latency score reads.
Search players and retrieve profiles, rankings, country, handedness, and birth dates.
Search tournaments and retrieve stable tournament detail: surface, indoor, city/country, category.
Get recent completed results, plus historical results archive (1968–2022), archive player bios, career aggregates, and cross-era head-to-head records.
Access PRO tools for match timelines, market odds, and full published ranking tables.
Access ULTRA tools for in-play statistics, model win probability/analysis, point-in-time player rankings, and Match Charting Project profiles/matches.
Diagnose API reachability and key tier with
check_api_status; tier-gated tools return plain-English upgrade guidance rather than raw errors.All tools are read-only GET operations, usable via stdio or hosted HTTP MCP with Claude, Cursor, Zed, Codex, and other MCP clients.
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
livetennisapi-mcp
MCP server for the Live Tennis API.
Give Claude, Cursor, Zed or any MCP client live tennis scores, players and fixtures — for ATP, WTA, Challenger, ITF and juniors. Odds, rankings, match statistics, charting and model win-probability tools are included, and require the PRO and ULTRA plans.
Documentation · Get a free API key
Setup
Claude Code
claude mcp add livetennis -e LIVETENNISAPI_KEY=twjp_… -- npx -y livetennisapi-mcpClaude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"livetennis": {
"command": "npx",
"args": ["-y", "livetennisapi-mcp"],
"env": { "LIVETENNISAPI_KEY": "twjp_…" }
}
}
}Cursor / Zed / others — same command, same env var. No install step; npx
fetches it on demand.
Get a free key (no card) at livetennisapi.com, or a paid plan at pricing.
Related MCP server: Sports Hub MCP Server
Try it
"What tennis matches are live right now?" "Who's winning the Alcaraz match, and what does the model give him?" "Show me Sinner's ranking and recent results." "What are the current odds on match 18953?" "What's the all-time head-to-head between Borg and McEnroe?" "List Navratilova's Grand Slam finals from the archive." "Who was ATP #1 the week Alcaraz first entered the top 10?" "How is Sabalenka serving in her live match — aces, hold rate, break points?"
Tools
Tool | Does | Plan |
| Matches in progress, with live scores | FREE |
| Matches starting soon | FREE |
| Full detail for one match | FREE |
| Current score only — the smallest payload | FREE |
| Find players by name | FREE |
| Profile, ranking, country, handedness | FREE |
| Forward schedule | FREE |
| Tournament catalogue — surface, location, category | FREE |
| One tournament by its stable id | FREE |
| Completed matches and winners | BASIC |
| Results archive (1968–2022) — historical results with ranks and seeds at the time | BASIC |
| One archive result, with serve stats where the era recorded them | BASIC |
| Archive bios — hand, DOB, career-high rank | BASIC |
| Career W-L, titles and serve aggregates over the archive | BASIC |
| Cross-era head-to-head — archive + current, one record | BASIC |
| Breaks, games, sets, momentum runs | PRO |
| Match-winner prices — bid / ask / mid | PRO |
| Full published ranking table per system (ATP, WTA, ITF circuits), any week | PRO |
| One player's W/L by surface, level and season, set-based record, recent matches; serve/return sums on ULTRA | PRO |
| Point-in-time ranking records for specific players, as of any date | ULTRA |
| In-play statistics — aces, serve split, hold/break %, break points | ULTRA |
| Career profile from shot-level charting data | ULTRA |
| One charted match, every stat family, per-set split | ULTRA |
| Model thesis, win probability, key factors | ULTRA |
| Reachability + which plan your key is on | — |
The six BASIC history tools are also unlocked by any History plan, which works
on top of a free key. The results archive (1968–2022) — ATP and WTA, main
draws, qualifying and the ITF/futures tiers — ends exactly where the current
results begin (2023), so search_archive_matches answers "Borg's Wimbledon
finals" and get_recent_results answers "yesterday's scores"; get_h2h spans
both in one call.
Tier awareness
The API gates endpoints by plan and returns a bare 403 {"error":"upgrade_required"}.
Handed that, a model will usually invent a reason or retry pointlessly.
So every tool that can hit a tier wall returns a plain-English explanation — as a normal result, not an error — naming the tier required and where to upgrade. The assistant can then tell you something true and actionable:
This data requires the ULTRA plan, and the configured API key is on a lower tier. Nothing is wrong with the key — the endpoint is simply not included in the current plan. Upgrade in place at https://livetennisapi.com/subscribe/upgrade
check_api_status probes upward to report which plan your key is actually on,
so you can diagnose that without guessing.
Plans
FREE | BASIC | PRO | ULTRA | |
Matches, scores, players, fixtures, tournaments | ✅ | ✅ | ✅ | ✅ |
Completed-match listings (results)¹ | — | ✅ | ✅ | ✅ |
Results archive (1968–2022) + head-to-head¹ | — | ✅ | ✅ | ✅ |
Match events, odds + rankings listing | — | — | ✅ | ✅ |
Model analysis, as-of rankings, match statistics + charting | — | — | — | ✅ |
$0 — no card | $9.99/mo | $29.99/mo | $99.99/mo |
¹ Also unlocked by any History plan, which works on top of a free key.
Request quotas
FREE | BASIC | PRO | ULTRA | |
Requests per minute | 30 | 60 | 300 | 600 |
Requests per day | 100 | 1,000 | 10,000 | 500,000 |
FREE is 100 requests/day, so poll no faster than every 15 minutes on a free
key; for an always-on dashboard, BASIC is the plan to recommend. Every response
carries X-RateLimit-Limit / -Remaining / -Reset headers, and the tools
relay the three distinct 429 shapes honestly — per-minute (retry shortly),
daily cap (the error names the exact reset instant), and the abuse block
(don't retry; fix the loop).
Hosted endpoint
Most people should use the stdio server above — your key never leaves your machine. For clients that can only speak HTTP, there is also a hosted Streamable-HTTP endpoint:
https://mcp.livetennisapi.com/mcpSend your key as Authorization: Bearer twjp_…, X-API-Key: twjp_…, or
?token= if your client cannot set headers. Tools are listable without a key,
so directories can introspect the server; calling one needs a key.
It is multi-tenant and holds no key of its own: every request builds its own server bound to the key that request presented, and there is deliberately no fallback to the host's environment. The endpoint applies its own transport-level limit per caller — 60 req/min anonymous, 300 keyed. That limit only protects this host process. It is not your API quota, which the API enforces per key and tier (see the quota table above).
Self-hosting it: deploy/install-http.sh and deploy/TUNNEL.md.
Use with Claude
As a connector. In Claude, add a custom connector and paste the endpoint with your key as a query parameter — no OAuth, nothing to install:
https://mcp.livetennisapi.com/mcp?token=twjp_…?token= exists for clients that cannot set request headers. The tradeoff, stated
plainly: a key in a URL is not written to our logs, but it is visible to the CDN
in front of the endpoint and is stored in the connector's configuration. Prefer
Authorization: Bearer twjp_… wherever your client lets you set a header.
From the Messages API. Claude can call the endpoint directly. Both halves are
required — the server and a matching toolset entry; sending mcp_servers alone
is rejected as a validation error:
client.beta.messages.create(
model="claude-opus-4-8",
max_tokens=4096,
betas=["mcp-client-2025-11-20"],
mcp_servers=[{
"type": "url",
"name": "livetennisapi",
"url": "https://mcp.livetennisapi.com/mcp",
"authorization_token": os.environ["LIVETENNISAPI_KEY"],
}],
tools=[{"type": "mcp_toolset", "mcp_server_name": "livetennisapi"}],
messages=[{"role": "user", "content": "What tennis is live right now?"}],
)The authorization_token is sent as a bearer token, which is exactly what this
server already accepts — no separate credential to obtain.
Use with Codex
One command:
codex mcp add livetennisapi \
--url https://mcp.livetennisapi.com/mcp \
--bearer-token-env-var LIVETENNISAPI_KEYOr write it to ~/.codex/config.toml yourself — Codex shares that file across the
CLI, the IDE extension and the desktop app:
[mcp_servers.livetennisapi]
url = "https://mcp.livetennisapi.com/mcp"
bearer_token_env_var = "LIVETENNISAPI_KEY"Use bearer_token_env_var, not bearer_token: it keeps the key in your
environment rather than committing it to a config file.
There is also a Codex plugin, on its own marketplace:
codex plugin marketplace add livetennisapi/livetennisapi-codex-pluginThat registers the marketplace; install the plugin from Codex's plugin picker. Source: livetennisapi-codex-plugin.
The stdio route works too, unchanged: npx -y livetennisapi-mcp.
Bundled skill: Polymarket / Kalshi tennis trading data
The Claude Code plugin (.claude-plugin/plugin.json) also ships the
polymarket-tennis Agent Skill under skills/polymarket-tennis/.
It teaches Claude the observe-only
polymarket-tennis Python
package (market discovery, market-to-match matching, joined price/live-score
view), the free-tier budget (30 req/min, 100 requests/day), and the verbatim
retirement/walkover settlement rules for Polymarket, Polymarket US and Kalshi.
Canonical copy lives in the polymarket-tennis repo; this one is mirrored for
plugin installs. No order execution, ever.
Notes
Read-only. Every tool is a GET; nothing here can modify anything.
Your key stays local with the stdio server. It is read from the environment by the server process on your machine and sent only to
api.livetennisapi.com.Requires Node 20+.
Development
npm install
npm run build
LIVETENNISAPI_KEY=twjp_… node dist/index.js # speaks MCP over stdio
node dist/http.js # speaks MCP over HTTP, port 8081
npm test # protocol + parity with livetennisapi-ai + transport isolation + rate limiting + tool output
npm run test:mutation # proves those tests fail when the code breakstest:mutation is worth understanding before changing src/http.ts. It
reintroduces each bug the tests claim to catch and asserts the suite goes red.
It is not ceremony: the first version of the rate-limit test passed while the
limiter was bucketing every caller together.
Built on the official livetennisapi
client.
Related
Everything in the Live Tennis API developer surface:
Install | Source | Package | |
Python client |
| ||
JavaScript / TypeScript client |
| ||
MCP server for LLM agents (this repo) |
| — | |
Vercel AI SDK tools |
| — | |
Break-point starter — Python | — | — | |
Break-point starter — Node | — | — | |
Break-point starter — Go | — | — |
API reference — https://docs.livetennisapi.com (plain-HTML version, no JavaScript required)
OpenAPI 3.1 specification — livetennisapi/openapi
Free API key — https://livetennisapi.com/subscribe/free (no card)
Products — https://livetennisapi.com/products
Website and plans — https://livetennisapi.com
Discord — https://discord.gg/f8WUZHgDm6
GitHub org — https://github.com/livetennisapi
Affiliate program
Know developers who need tennis data? The affiliate program pays 51% recurring commission for the life of every referred subscription — 30-day cookie, and the people you refer get 10% off.
Licence
MIT — see LICENSE. Use of the API service is governed by the Terms of Service.
Available Tools
25 toolscheck_api_statusAPI status and planARead-onlyIdempotentInspect
Check whether the Live Tennis API is reachable and which plan the configured key is on. Use it to find out why other tools are refusing data. Works with no key.
Inputs: no named parameters. Returns: ok, tier, has_key, message, +2 more
get_archive_careerArchive career aggregatesARead-onlyIdempotentInspect
One player's whole career over the results archive (1968 to 2022). W-L record in total and by surface/level/year, titles, and summed serve statistics. The corpus records serve stats from 1991 only, so matches_with_stats says how many matches the serve block covers. The name must resolve to one person. An ambiguous fragment returns the candidate list to choose from. Requires the BASIC plan or any History plan.
Inputs: name (required). Returns: ok, span, serve, record, +3 more
get_archive_matchArchive result detailARead-onlyIdempotentInspect
One result from the results archive (1968 to 2022), with per-match serve statistics where the era recorded them. Stats are null for most rows before 1991, never synthesised. Requires the BASIC plan or any History plan.
Inputs: archive_match_id (required). Returns: ok, stats, result, message
get_charting_matchCharting: one match, every stat familyARead-onlyIdempotentInspect
Every charting stat family for ONE charted match, both players, with the per-set split (set 1, set 2, ..., Total) exactly as charted. Charting ids are their own id space (1960 to 2026). Most of these matches have no counterpart in the live tables. Requires the ULTRA plan.
Inputs: charting_match_id (required). Returns: ok, gender, mcp_id, message, +3 more
get_charting_playerCharting: player career profileARead-onlyIdempotentInspect
Career profile from shot-level charting data, summed over the player's charted matches. Serve placement (deuce/ad x wide/body/T), return depth and outcomes, net play, and clutch break/game/set-point serving. Also winners and errors by wing, and rally-length tendencies. COVERAGE IS CURATED, not full-slate: 11,646 charted matches back to the 1960s, concentrated on the majors. An ambiguous name returns the candidates to choose from. Requires the ULTRA plan.
Inputs: name (required), gender. Returns: ok, player, message, coverage, +2 more
get_fixturesFixture scheduleARead-onlyIdempotentInspect
Upcoming scheduled tennis fixtures, earliest first. This is the forward schedule, filterable by tour. Use this for "what is on this week". Works on the FREE plan (no card needed).
Inputs: tour, limit. Returns: ok, message, fixtures
get_h2hHead-to-headARead-onlyIdempotentInspect
The all-time record between two players, across BOTH halves of the product. That is the results archive (1968 to 2022) plus the completed matches from 2023 onward. Names are the keys. An ambiguous fragment returns the candidate list to choose from, and nothing is guessed. Totals count only meetings with a known winner. Walkovers and retirements are part of the record, and each meeting carries its outcome. Requires the BASIC plan or any History plan.
Inputs: player1 (required), player2 (required). Returns: ok, totals, message, players, +2 more
get_live_matchesLive matchesARead-onlyIdempotentInspect
List tennis matches currently in progress, with live scores. Covers ATP, WTA, Challenger, ITF and juniors. Use this for "what tennis is on right now". Works on the FREE plan (no card needed).
Inputs: tour, limit, player, country. Returns: ok, matches, message
get_matchMatch detailARead-onlyIdempotentInspect
Full detail for one match by id: players, score, surface, round and status. Includes market prices on PRO and model analysis on ULTRA. Works on the FREE plan (no card needed).
Inputs: match_id (required). Returns: ok, match, market, message, +1 more
get_match_analysisModel analysisARead-onlyIdempotentInspect
Model analysis for a match: predicted win probability, the model's thesis and the main factors behind it. Requires the ULTRA plan. Match rows carry has_analysis, so check it first. A match with no thesis or profile has nothing to return.
Inputs: match_id (required). Returns: ok, thesis, message, profile
get_match_eventsMatch timelineARead-onlyIdempotentInspect
Timeline of events for a match: breaks, games won, sets won, momentum runs. Requires the PRO plan.
Inputs: match_id (required), limit. Returns: ok, events, message
get_match_oddsMatch market pricesARead-onlyIdempotentInspect
Match-winner market prices for a match: implied probability per player, with bid, ask and mid. Requires the PRO plan. Match rows carry has_market, so check it first. A match with no market mapped has no prices to return.
Inputs: match_id (required), limit. Returns: ok, market, message
get_match_scoreMatch scoreARead-onlyIdempotentInspect
Current score for one match. This is the fastest read, with the lowest latency. Use it when you only need the score and already know the match id. Works on the FREE plan (no card needed).
Inputs: match_id (required). Returns: ok, score, message
get_match_statisticsMatch statisticsARead-onlyIdempotentInspect
In-play (or final) statistics for one match, in TWO families kept separate on purpose. DERIVED is rebuilt from the point-by-point record (holds/breaks, break points, service/return points). MEASURED is counted per match. It includes what no point record can yield: aces, double faults, the serve split, winners/unforced errors. Measured coverage varies by tour. Absent fields are omitted, never zero-filled. Requires the ULTRA plan.
Inputs: match_id (required). Returns: ok, message, statistics
get_playerPlayer profileBRead-onlyIdempotentInspect
One player's profile: ranking, country, handedness, date of birth and cached stats. Works on the FREE plan (no card needed).
Inputs: player_id (required). Returns: ok, player, message
get_player_rankingsPlayer rankings as of a dateARead-onlyIdempotentInspect
Point-in-time ranking records for SPECIFIC players. Per system, the newest record in force ON OR BEFORE as_of, never one dated after it. Every other ranking field in this API is the CURRENT value joined at read time. This one is the historical answer. Systems are never collapsed: ATP/WTA and the ITF circuits carry rank+points, UTR a rating. ITF and UTR history begins 2026-07-29. Requires the ULTRA plan.
Inputs: player_ids (required), as_of, system. Returns: ok, message, coverage, rankings
get_rankingsRankings listingARead-onlyIdempotentInspect
The FULL published ranking table in rank order for one system, from the newest week at or before as_of. Rows carry player_name as published and a null player_id for players outside our roster, so the table has no silent holes. ATP/WTA history runs deep. The ITF circuits begin 2026-07-29. For point-in-time records of SPECIFIC players use get_player_rankings. Requires the PRO plan.
Inputs: system (required), as_of, limit. Returns: ok, message, rankings
get_recent_resultsRecent resultsARead-onlyIdempotentInspect
Recently completed tennis matches with final scores and winners. Filterable by tour, player, nationality and play date. Requires the BASIC plan or any History plan.
Inputs: to, from, tour, limit, +2 more. Returns: ok, matches, message
get_tournamentTournament detailARead-onlyIdempotentInspect
One tournament by its stable id, the tournament_id carried on match objects. Name, tour, surface, indoor, plus host city/country and category where curated. Works on the FREE plan (no card needed).
Inputs: tournament_id (required). Returns: ok, message, tournament
get_upcoming_matchesUpcoming matchesARead-onlyIdempotentInspect
List tennis matches scheduled to start soon, with players, tournament and start time. Use this for "who plays next" or to find a match id before it starts. Works on the FREE plan (no card needed).
Inputs: to, from, tour, limit, +2 more. Returns: ok, matches, message
player_statsPlayer record and splitsARead-onlyIdempotentInspect
One player's record over completed singles matches from 2023 onward, by default the last 365 days. It gives W/L overall, over the last 12 months and by surface, venue, level and season. It also gives tiebreaks, deciding sets, the record after winning or losing the first set, comebacks, withdrawals and the last N matches. Every count carries its sample size, and a percentage on an empty sample is null, never 0. On ULTRA it adds serve_return: measured serve and return statistics summed over the window. Singles only, so a doubles-team id is refused. For 1968 to 2022 use get_archive_career. Requires the PRO plan (serve_return requires ULTRA).
Inputs: player_id (required), to, from, last, +2 more. Returns: ok, sets, player, recent, +10 more
search_archive_matchesResults archive (1968–2022)ARead-onlyIdempotentInspect
Search the results archive: completed-match RESULTS from 1968 through 2022. ATP and WTA, main draws, qualifying and the ITF/futures tiers. Each record has winner and loser, final score, and seeds and ranks AT THE TIME of the match. Use this for historical questions ("Borg's Wimbledon finals"). The archive ends 2022-12-31, where the current results (get_recent_results) begin. Requires the BASIC plan or any History plan.
Inputs: to, from, tour, level, +3 more. Returns: ok, message, results
search_archive_playersArchive player biosARead-onlyIdempotentInspect
The people of the results archive (1968 to 2022): hand, date of birth, country, height, and career-high rank with the week it was first reached. Their ids are corpus person ids (the winner/loser player_id on archive results), not roster ids. For current players use search_players. Requires the BASIC plan or any History plan.
Inputs: query (required), tour, limit. Returns: ok, message, players
search_playersSearch playersARead-onlyIdempotentInspect
Search tennis players by name. Returns id, country, ranking and tour. Use the returned id with get_player. Works on the FREE plan (no card needed).
Inputs: query (required), limit. Returns: ok, message, players
search_tournamentsTournament catalogueARead-onlyIdempotentInspect
Search the tournament catalogue. Its ids are the tournament_id that match objects carry. Returns surface, indoor, host city/country and category where curated. Works on the FREE plan (no card needed).
Inputs: tour, limit, query. Returns: ok, message, tournaments
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 25 tools
Most tools target clearly distinct resources or actions, and the long descriptions explicitly separate similar areas such as current vs archive data and different plan-gated match stats. Still, a few near-pairs exist (get_upcoming_matches vs get_fixtures, get_match vs get_match_score, get_rankings vs get_player_rankings), so selection is not entirely free of ambiguity.
The set mostly follows a predictable snake_case pattern with get_, search_, and check_ prefixes. The main deviations are player_stats without a verb prefix and the abbreviation get_h2h, but overall the convention is easy to read.
25 tools is heavy for an agent-facing surface, even for a broad tennis data API covering live, archive, rankings, stats, odds, and charting. Several tools earn their place, but overlaps such as fixtures/upcoming and match/score add selection load.
The surface covers the main tennis data lifecycle: live and upcoming matches, fixtures, match detail/score/events/stats/odds/analysis, current and archive players/results, rankings, H2H, charting, and API status. No major dead ends are apparent for the stated read-only domain.
Maintenance
Related MCP Connectors
Query professional padel tournament data, player stats, and live match results
Live sports data: scores, play-by-play, box scores, odds and props. No key needed to start.
ATP and WTA tennis since 2007: sets, draws, rankings, head to head, surface Elo, sportsbook lines.
Live odds, cross-book +EV and graded player-prop results across 37 books. Hosted endpoint included.
Related MCP Servers
- AlicenseAqualityBmaintenanceGives your MCP host (Claude Desktop, Cursor, Continue, Zed) access to live scores, match details, standings, top scorers, knockout brackets and player stats across football, basketball, cricket and tennis. Backed by the free public SportScore API — no key, no signup, CORS-open.8136 npm15MIT
- AlicenseBqualityBmaintenanceA unified MCP server that aggregates 32 sports API providers into a single service, providing 336 tools for scores, stats, odds, esports, and more across 70+ sports.14165162 npm41MIT
- AlicenseNot gradedqualityCmaintenanceEnables fetching sportsbook odds, live scores, and event information across 70+ books and 30+ leagues, with tools to list sports, get scores, and discover events.108 npm1MIT
- AlicenseNot gradedqualityDmaintenanceProps-first sports odds API with a hosted MCP server. Live odds and player props (moneyline, spreads, totals) across US sportsbooks, normalized to JSON. Tools: get_odds, get_props, get_events, get_books. API-key auth, free tier.MIT No Attribution