Skip to main content
Glama
livetennisapi-mcp

livetennisapi-mcp

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

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

Claude 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

get_live_matches

Matches in progress, with live scores

FREE

get_upcoming_matches

Matches starting soon

FREE

get_match

Full detail for one match

FREE

get_match_score

Current score only — the smallest payload

FREE

search_players

Find players by name

FREE

get_player

Profile, ranking, country, handedness

FREE

get_fixtures

Forward schedule

FREE

search_tournaments

Tournament catalogue — surface, location, category

FREE

get_tournament

One tournament by its stable id

FREE

get_recent_results

Completed matches and winners

BASIC

search_archive_matches

Results archive (1968–2022) — historical results with ranks and seeds at the time

BASIC

get_archive_match

One archive result, with serve stats where the era recorded them

BASIC

search_archive_players

Archive bios — hand, DOB, career-high rank

BASIC

get_archive_career

Career W-L, titles and serve aggregates over the archive

BASIC

get_h2h

Cross-era head-to-head — archive + current, one record

BASIC

get_match_events

Breaks, games, sets, momentum runs

PRO

get_match_odds

Match-winner prices — bid / ask / mid

PRO

get_rankings

Full published ranking table per system (ATP, WTA, ITF circuits), any week

PRO

player_stats

One player's W/L by surface, level and season, set-based record, recent matches; serve/return sums on ULTRA

PRO

get_player_rankings

Point-in-time ranking records for specific players, as of any date

ULTRA

get_match_statistics

In-play statistics — aces, serve split, hold/break %, break points

ULTRA

get_charting_player

Career profile from shot-level charting data

ULTRA

get_charting_match

One charted match, every stat family, per-set split

ULTRA

get_match_analysis

Model thesis, win probability, key factors

ULTRA

check_api_status

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

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_KEY

Or 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-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

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

Everything in the Live Tennis API developer surface:

Install

Source

Package

Python client

pip install livetennisapi

repo

package

JavaScript / TypeScript client

npm install livetennisapi

repo

package

MCP server for LLM agents (this repo)

npx livetennisapi-mcp

—

package

Vercel AI SDK tools

npm install livetennisapi-ai

repo

—

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.

Available Tools

25 tools
check_api_statusAPI status and planA
Read-onlyIdempotent
Inspect

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 aggregatesA
Read-onlyIdempotent
Inspect

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 detailA
Read-onlyIdempotent
Inspect

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 familyA
Read-onlyIdempotent
Inspect

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 profileA
Read-onlyIdempotent
Inspect

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 scheduleA
Read-onlyIdempotent
Inspect

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-headA
Read-onlyIdempotent
Inspect

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 matchesA
Read-onlyIdempotent
Inspect

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 detailA
Read-onlyIdempotent
Inspect

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 analysisA
Read-onlyIdempotent
Inspect

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 timelineA
Read-onlyIdempotent
Inspect

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 pricesA
Read-onlyIdempotent
Inspect

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 scoreA
Read-onlyIdempotent
Inspect

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 statisticsA
Read-onlyIdempotent
Inspect

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 profileB
Read-onlyIdempotent
Inspect

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 dateA
Read-onlyIdempotent
Inspect

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 listingA
Read-onlyIdempotent
Inspect

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 resultsA
Read-onlyIdempotent
Inspect

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 detailA
Read-onlyIdempotent
Inspect

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 matchesA
Read-onlyIdempotent
Inspect

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 splitsA
Read-onlyIdempotent
Inspect

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)A
Read-onlyIdempotent
Inspect

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 biosA
Read-onlyIdempotent
Inspect

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 playersA
Read-onlyIdempotent
Inspect

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 catalogueA
Read-onlyIdempotent
Inspect

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

    A3.9/5.0

    Scored across 25 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness5/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Gives 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.
      8
      136 npm
      15
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      A 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.
      14
      165
      162 npm
      41
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Props-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