Livetennisapi Mcp

io.github.livetennisapiPublished by GitHub account livetennisapiv1.6.5Updated Oct 30, 2026

Live tennis scores, players, rankings, odds and win-probability. ATP, WTA, Challenger, ITF, juniors.

VerifiedStreamable HTTPWeb executableLocation & LifestyleFinanceData & Analytics

Overview

AI-generated overview

Live Tennis API MCP server giving an assistant live tennis scores, players, fixtures, rankings, odds and model win probabilities across ATP, WTA, Challenger…

What you can do
  • Look up live and upcoming matches, scores, fixtures, tournaments and player profiles
  • Search players and tournaments, and read full detail for a single match or tournament
  • Browse completed results and the 1968-2022 results archive, including career records and cross-era head-to-head
  • Read published ranking tables and point-in-time ranking records for specific players
  • Fetch match events, market odds, in-play statistics, charting profiles and model win-probability analysis
  • Check API reachability and which plan the configured key is on
When to use it
Useful when you want an assistant to answer tennis questions from live data: what is on right now, who plays next, a player's ranking and record, historical results, head-to-heads, or odds and model probabilities for a match. Most live and catalogue tools work on a free key; history, odds, statistics and analysis need paid plans.
Requirements
Either the hosted Streamable-HTTP endpoint or the local npm package run with npx, which needs Node 20 or newer. An API key is required to call tools: LIVETENNISAPI_KEY for the local server, or an Authorization bearer token (or query token) for the hosted endpoint. A free key is available without a card; paid plans unlock history, odds, statistics and analysis. Network access to the API is needed.
Before you install
The API key is a credential: with the hosted endpoint it is sent to a third party, and passing it as a query token exposes it to the CDN and stores it in the client configuration, so a header is preferable. Paid tiers cost money (BASIC, PRO and ULTRA are monthly subscriptions) and free-tier quotas are limited to 100 requests per day. Tools are read-only GET calls, so nothing is modified, but match data and odds come from a third-party service.

Installation

In SourceWeft

  1. Open Livetennisapi Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.livetennisapi%2Flivetennisapi-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config.

{
  "mcpServers": {
    "livetennisapi": {
      "type": "http",
      "url": "https://mcp.livetennisapi.com/mcp"
    }
  }
}

README

[Live Tennis API]

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.

[CI] [npm] [license]

Documentation · Get a free API key


Setup

Claude Code

bash
claude mcp add livetennis -e LIVETENNISAPI_KEY=twjp_… -- npx -y livetennisapi-mcp

Claude Desktop — add to claude_desktop_config.json:

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.

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

ToolDoesPlan
get_live_matchesMatches in progress, with live scoresFREE
get_upcoming_matchesMatches starting soonFREE
get_matchFull detail for one matchFREE
get_match_scoreCurrent score only — the smallest payloadFREE
search_playersFind players by nameFREE
get_playerProfile, ranking, country, handednessFREE
get_fixturesForward scheduleFREE
search_tournamentsTournament catalogue — surface, location, categoryFREE
get_tournamentOne tournament by its stable idFREE
get_recent_resultsCompleted matches and winnersBASIC
search_archive_matchesResults archive (1968–2022) — historical results with ranks and seeds at the timeBASIC
get_archive_matchOne archive result, with serve stats where the era recorded themBASIC
search_archive_playersArchive bios — hand, DOB, career-high rankBASIC
get_archive_careerCareer W-L, titles and serve aggregates over the archiveBASIC
get_h2hCross-era head-to-head — archive + current, one recordBASIC
get_match_eventsBreaks, games, sets, momentum runsPRO
get_match_oddsMatch-winner prices — bid / ask / midPRO
get_rankingsFull published ranking table per system (ATP, WTA, ITF circuits), any weekPRO
player_statsOne player's W/L by surface, level and season, set-based record, recent matches; serve/return sums on ULTRAPRO
get_player_rankingsPoint-in-time ranking records for specific players, as of any dateULTRA
get_match_statisticsIn-play statistics — aces, serve split, hold/break %, break pointsULTRA
get_charting_playerCareer profile from shot-level charting dataULTRA
get_charting_matchOne charted match, every stat family, per-set splitULTRA
get_match_analysisModel thesis, win probability, key factorsULTRA
check_api_statusReachability + 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

FREEBASICPROULTRA
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

FREEBASICPROULTRA
Requests per minute3060300600
Requests per day1001,00010,000500,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/mcp

Send 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:

python
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:

bash
codex mcp add livetennisapi \  --url https://mcp.livetennisapi.com/mcp \  --bearer-token-env-var LIVETENNISAPI_KEY

Or write it to ~/.codex/config.toml yourself — Codex shares that file across the CLI, the IDE extension and the desktop app:

toml
[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:

bash
codex plugin marketplace add livetennisapi/livetennisapi-codex-plugin

That 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

bash
npm installnpm run buildLIVETENNISAPI_KEY=twjp_… node dist/index.js   # speaks MCP over stdionode dist/http.js                             # speaks MCP over HTTP, port 8081
npm test               # protocol + parity with livetennisapi-ai + transport isolation + rate limiting + tool outputnpm run test:mutation  # proves those tests fail when the code breaks

test: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:

InstallSourcePackage
Python clientpip install livetennisapirepopackage
JavaScript / TypeScript clientnpm install livetennisapirepopackage
MCP server for LLM agents (this repo)npx livetennisapi-mcp—package
Vercel AI SDK toolsnpm install livetennisapi-airepo—
Break-point starter — Python—repo—
Break-point starter — Node—repo—
Break-point starter — Go—repo—

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.

Source: README.md at commit 679733e

Tools

25

get_live_matches

Live matches

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).

Parameterstourlimitplayercountry

get_upcoming_matches

Upcoming matches

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).

Parameterstofromtourlimitplayercountry

get_match

Match detail

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).

Parametersmatch_idrequired

get_match_score

Match score

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).

Parametersmatch_idrequired

search_players

Search players

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).

Parameterslimitqueryrequired

get_player

Player profile

One player's profile: ranking, country, handedness, date of birth and cached stats. Works on the FREE plan (no card needed).

Parametersplayer_idrequired

get_fixtures

Fixture schedule

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).

Parameterstourlimit

search_tournaments

Tournament catalogue

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).

Parameterstourlimitquery

get_tournament

Tournament detail

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).

Parameterstournament_idrequired

get_recent_results

Recent results

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.

Parameterstofromtourlimitplayercountry

search_archive_matches

Results archive (1968–2022)

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.

Parameterstofromtourlevellimitroundplayer_name

get_archive_match

Archive result detail

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.

Parametersarchive_match_idrequired

search_archive_players

Archive player bios

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.

Parameterstourlimitqueryrequired

get_archive_career

Archive career aggregates

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.

Parametersnamerequired

get_h2h

Head-to-head

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.

Parametersplayer1requiredplayer2required

get_match_events

Match timeline

Timeline of events for a match: breaks, games won, sets won, momentum runs. Requires the PRO plan.

Parameterslimitmatch_idrequired

get_match_odds

Match market prices

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.

Parameterslimitmatch_idrequired

get_rankings

Rankings listing

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.

Parametersas_oflimitsystemrequired

player_stats

Player record and splits

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).

Parameterstofromlastlevelsurfaceplayer_idrequired

get_match_analysis

Model analysis

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.

Parametersmatch_idrequired

get_player_rankings

Player rankings as of a date

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.

Parametersas_ofsystemplayer_idsrequired

get_match_statistics

Match statistics

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.

Parametersmatch_idrequired

get_charting_player

Charting: player career profile

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.

Parametersnamerequiredgender

get_charting_match

Charting: one match, every stat family

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.

Parameterscharting_match_idrequired

check_api_status

API status and plan

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.

Takes no parameters.

Version history

2
  1. v1.6.5LatestOct 29, 2026
  2. v1.5.0Sep 16, 2026

Score

100% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts