io.github.livetennisapi/livetennisapi-mcp

Official24 toolsLive

by livetennisapi · TypeScript

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

LiveTennisAPI MCP Server

This MCP server provides live tennis data—scores, players, and fixtures—via the Model Context Protocol. It covers ATP, WTA, Challenger, ITF, and juniors, and includes odds, rankings, match statistics, charting, and model win-probability tools (the latter require PRO and ULTRA plans).

🛠️ Key Features

Live tennis scores
Players and fixtures
Odds and rankings
Match statistics
Charting
Model win-probability tools
Tooling for ATP, WTA, Challenger, ITF, and juniors
24 tools available

🚀 Use Cases

Fetching live match information
Getting player-related data
Retrieving odds and rankings for tennis competitions
Accessing match statistics and charting outputs
Supporting model-driven win-probability workflows (PRO/ULTRA)

⚡ Developer Benefits

MCP-compatible integration with MCP clients (e.g., Claude/Cursor/Zed)
Clear tennis domain coverage across multiple competition levels
Structured tool set (24 tools) for sports data retrieval and analysis

⚠️ Limitations

Odds, rankings, match statistics, charting, and win-probability tools require the PRO and ULTRA plans.

Topics

aiclaudelive-scoresllmmcpmcp-servermodel-context-protocolsports-apisports-datatennistennis-apitypescript

Captured live from the server via tools/list.

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

Parameters4

tour	string	optional	Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used.
player	array	optional	Player ids (from search_players), max 50 — keeps matches where ANY listed player is either participant.
country	string	optional	Either participant's country — the lowercase 3-letter IOC-style code the Player object returns (e.g. ned, sui, gre), NOT ISO-3166. Players with no recorded country never match.
limit	integer	optional	Maximum matches to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "challenger",
        "itf",
        "juniors"
      ],
      "description": "Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used."
    },
    "player": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "maxItems": 50,
      "description": "Player ids (from search_players), max 50 — keeps matches where ANY listed player is either participant."
    },
    "country": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "description": "Either participant's country — the lowercase 3-letter IOC-style code the Player object returns (e.g. ned, sui, gre), NOT ISO-3166. Players with no recorded country never match."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum matches to return (1-200)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_upcoming_matches

List tennis matches scheduled to start soon, with players and tournament.

Parameters6

tour	string	optional	Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used.
player	array	optional	Player ids (from search_players), max 50 — keeps matches where ANY listed player is either participant.
country	string	optional	Either participant's country — the lowercase 3-letter IOC-style code the Player object returns (e.g. ned, sui, gre), NOT ISO-3166. Players with no recorded country never match.
from	string	optional	Earliest play date: YYYY-MM-DD (a whole UTC day) or ISO-8601 datetime.
to	string	optional	Latest play date: YYYY-MM-DD or ISO-8601; must not precede from.
limit	integer	optional	Maximum matches to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "challenger",
        "itf",
        "juniors"
      ],
      "description": "Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used."
    },
    "player": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "maxItems": 50,
      "description": "Player ids (from search_players), max 50 — keeps matches where ANY listed player is either participant."
    },
    "country": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "description": "Either participant's country — the lowercase 3-letter IOC-style code the Player object returns (e.g. ned, sui, gre), NOT ISO-3166. Players with no recorded country never match."
    },
    "from": {
      "type": "string",
      "description": "Earliest play date: YYYY-MM-DD (a whole UTC day) or ISO-8601 datetime."
    },
    "to": {
      "type": "string",
      "description": "Latest play date: YYYY-MM-DD or ISO-8601; must not precede from."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum matches to return (1-200)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_match

Full detail for one match by id: players, score, surface, round and status. Includes market prices on PRO and model analysis on ULTRA.

Parameters1

match_id

integer

required

Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results.

Raw schema

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "integer",
      "description": "Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_match_score

Current score for one match — the fastest, lowest-latency read. Use this when you only need the score and already know the match id.

Parameters1

match_id

integer

required

Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results.

Raw schema

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "integer",
      "description": "Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_players

Search tennis players by name. Returns id, country, ranking and tour. Use the returned id with get_player.

Parameters2

query	string	required	Full or partial player name, e.g. "alcaraz".
limit	integer	optional	Maximum players to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Full or partial player name, e.g. \"alcaraz\"."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 10,
      "description": "Maximum players to return (1-200)."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_player

One player's profile: ranking, country, handedness, date of birth and cached stats.

Parameters1

player_id

integer

required

Player id, as returned by search_players.

Raw schema

{
  "type": "object",
  "properties": {
    "player_id": {
      "type": "integer",
      "description": "Player id, as returned by search_players."
    }
  },
  "required": [
    "player_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_fixtures

Upcoming scheduled tennis fixtures, earliest first — the forward schedule.

Parameters2

tour	string	optional	Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used.
limit	integer	optional	Maximum fixtures to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "challenger",
        "itf",
        "juniors"
      ],
      "description": "Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum fixtures to return (1-200)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_tournaments

Search the tournament catalogue — the stable id space that match objects carry as tournament_id. Returns surface, indoor, host city/country and category where curated.

Parameters3

query	string	optional	Full or partial tournament name, e.g. "wimbledon". Omit to list all.
tour	string	optional	Restrict to one tour.
limit	integer	optional	Maximum tournaments to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Full or partial tournament name, e.g. \"wimbledon\". Omit to list all."
    },
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "challenger",
        "itf",
        "juniors"
      ],
      "description": "Restrict to one tour."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum tournaments to return (1-200)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_tournament

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.

Parameters1

tournament_id

string

required

Stable tournament id, as returned by search_tournaments or carried on a match as tournament_id.

Raw schema

{
  "type": "object",
  "properties": {
    "tournament_id": {
      "type": "string",
      "description": "Stable tournament id, as returned by search_tournaments or carried on a match as tournament_id."
    }
  },
  "required": [
    "tournament_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

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

Parameters6

tour	string	optional	Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used.
player	array	optional	Player ids (from search_players), max 50 — keeps matches where ANY listed player is either participant.
country	string	optional	Either participant's country — the lowercase 3-letter IOC-style code the Player object returns (e.g. ned, sui, gre), NOT ISO-3166. Players with no recorded country never match.
from	string	optional	Earliest play date: YYYY-MM-DD (a whole UTC day) or ISO-8601 datetime.
to	string	optional	Latest play date: YYYY-MM-DD or ISO-8601; must not precede from.
limit	integer	optional	Maximum matches to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "challenger",
        "itf",
        "juniors"
      ],
      "description": "Tour filter; each name covers its doubles variants. Exhibition/team events carry no tour and are excluded whenever the filter is used."
    },
    "player": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "maxItems": 50,
      "description": "Player ids (from search_players), max 50 — keeps matches where ANY listed player is either participant."
    },
    "country": {
      "type": "string",
      "minLength": 3,
      "maxLength": 3,
      "description": "Either participant's country — the lowercase 3-letter IOC-style code the Player object returns (e.g. ned, sui, gre), NOT ISO-3166. Players with no recorded country never match."
    },
    "from": {
      "type": "string",
      "description": "Earliest play date: YYYY-MM-DD (a whole UTC day) or ISO-8601 datetime."
    },
    "to": {
      "type": "string",
      "description": "Latest play date: YYYY-MM-DD or ISO-8601; must not precede from."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum matches to return (1-200)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_archive_matches

Search the results archive — completed-match RESULTS from 1968 through 2022: ATP and WTA, main draws, qualifying and the ITF/futures tiers. Winner/loser-shaped records with final score, 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 our own results (get_recent_results) begin. Requires the BASIC plan or any History plan.

Parameters7

player_name	string	optional	Case-insensitive fragment of EITHER player's name, min 3 chars, e.g. "borg".
tour	string	optional	atp or wta.
from	string	optional	Earliest tournament START date, YYYY-MM-DD.
to	string	optional	Latest tournament START date, YYYY-MM-DD.
round	string	optional	Round code, e.g. F for finals.
level	string	optional	Source tier code: G=grand slam, M=masters, A=tour, F=finals, D=davis cup, C=challenger, O=olympics, or a futures category code (e.g. 15).
limit	integer	optional	Maximum results to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "player_name": {
      "type": "string",
      "minLength": 3,
      "description": "Case-insensitive fragment of EITHER player's name, min 3 chars, e.g. \"borg\"."
    },
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta"
      ],
      "description": "atp or wta."
    },
    "from": {
      "type": "string",
      "description": "Earliest tournament START date, YYYY-MM-DD."
    },
    "to": {
      "type": "string",
      "description": "Latest tournament START date, YYYY-MM-DD."
    },
    "round": {
      "type": "string",
      "enum": [
        "F",
        "SF",
        "QF",
        "R16",
        "R32",
        "R64",
        "R128",
        "RR",
        "BR",
        "Q1",
        "Q2",
        "Q3",
        "Q4",
        "ER"
      ],
      "description": "Round code, e.g. F for finals."
    },
    "level": {
      "type": "string",
      "description": "Source tier code: G=grand slam, M=masters, A=tour, F=finals, D=davis cup, C=challenger, O=olympics, or a futures category code (e.g. 15)."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum results to return (1-200)."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_archive_match

One result from the results archive (1968–2022), with per-match serve statistics where the era recorded them — stats are null for most rows before 1991, honestly, never synthesised. Requires the BASIC plan or any History plan.

Parameters1

archive_match_id

integer

required

Archive match id, as returned by search_archive_matches.

Raw schema

{
  "type": "object",
  "properties": {
    "archive_match_id": {
      "type": "integer",
      "description": "Archive match id, as returned by search_archive_matches."
    }
  },
  "required": [
    "archive_match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

search_archive_players

The people of the results archive (1968–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.

Parameters3

query	string	required	Full or partial player name, min 3 chars, e.g. "navratilova".
tour	string	optional	atp or wta.
limit	integer	optional	Maximum players to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 3,
      "description": "Full or partial player name, min 3 chars, e.g. \"navratilova\"."
    },
    "tour": {
      "type": "string",
      "enum": [
        "atp",
        "wta"
      ],
      "description": "atp or wta."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 10,
      "description": "Maximum players to return (1-200)."
    }
  },
  "required": [
    "query"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_archive_career

One player's whole career over the results archive (1968–2022): W-L record overall and by surface/level/year, titles, and summed serve statistics with honest coverage — the corpus records serve stats from 1991 only, so matches_with_stats states 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.

Parameters1

name

string

required

Player name fragment, min 3 chars — must resolve to exactly one person.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 3,
      "description": "Player name fragment, min 3 chars — must resolve to exactly one person."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_h2h

The all-time record between two players, across BOTH halves of the product: the results archive (1968–2022) plus our own completed matches (2023 onward). Names are the keys — an ambiguous fragment returns the candidate list to choose from rather than guessing. 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.

Parameters2

player1	string	required	First player name (fragment, min 3 chars), e.g. "federer".
player2	string	required	Second player name (fragment, min 3 chars), e.g. "nadal".

Raw schema

{
  "type": "object",
  "properties": {
    "player1": {
      "type": "string",
      "minLength": 3,
      "description": "First player name (fragment, min 3 chars), e.g. \"federer\"."
    },
    "player2": {
      "type": "string",
      "minLength": 3,
      "description": "Second player name (fragment, min 3 chars), e.g. \"nadal\"."
    }
  },
  "required": [
    "player1",
    "player2"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_match_events

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

Parameters2

match_id	integer	required	Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results.
limit	integer	optional	Maximum events to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "integer",
      "description": "Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 30,
      "description": "Maximum events to return (1-200)."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_match_odds

Match-winner market prices for a match — implied probability per player, with bid, ask and mid. Requires the PRO plan.

Parameters2

match_id	integer	required	Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results.
limit	integer	optional	Maximum price points to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "integer",
      "description": "Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 10,
      "description": "Maximum price points to return (1-200)."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_rankings

The FULL published ranking table in rank order for one system — 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.

Parameters3

system	string	required	Ranking system to list. utr has no listing — it is a rating, not a ranking.
as_of	string	optional	YYYY-MM-DD — serves the newest published week at or before this date. Omit for latest.
limit	integer	optional	Maximum ranking rows to return (1-200).

Raw schema

{
  "type": "object",
  "properties": {
    "system": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "itf_jt",
        "itf_mt",
        "itf_wt"
      ],
      "description": "Ranking system to list. utr has no listing — it is a rating, not a ranking."
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD — serves the newest published week at or before this date. Omit for latest."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "maximum": 200,
      "default": 20,
      "description": "Maximum ranking rows to return (1-200)."
    }
  },
  "required": [
    "system"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_match_analysis

Model analysis for a match: predicted win probability, the model's thesis and the key factors behind it. Requires the ULTRA plan.

Parameters1

match_id

integer

required

Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results.

Raw schema

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "integer",
      "description": "Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_player_rankings

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

Parameters3

player_ids	array	required	Roster player ids, as returned by search_players. Max 50.
as_of	string	optional	YYYY-MM-DD — the record in force on this date. Omit for the latest known.
system	string	optional	Restrict to one system. Omit for every system held for the player.

Raw schema

{
  "type": "object",
  "properties": {
    "player_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "minItems": 1,
      "maxItems": 50,
      "description": "Roster player ids, as returned by search_players. Max 50."
    },
    "as_of": {
      "type": "string",
      "description": "YYYY-MM-DD — the record in force on this date. Omit for the latest known."
    },
    "system": {
      "type": "string",
      "enum": [
        "atp",
        "wta",
        "itf_jt",
        "itf_mt",
        "itf_wt",
        "utr"
      ],
      "description": "Restrict to one system. Omit for every system held for the player."
    }
  },
  "required": [
    "player_ids"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_match_statistics

In-play (or final) statistics for one match, in TWO families kept deliberately separate: DERIVED is rebuilt from the point-by-point record (holds/breaks, break points, service/return points); MEASURED is counted upstream and 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.

Parameters1

match_id

integer

required

Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results.

Raw schema

{
  "type": "object",
  "properties": {
    "match_id": {
      "type": "integer",
      "description": "Match id, as returned by get_live_matches, get_upcoming_matches or get_recent_results."
    }
  },
  "required": [
    "match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_charting_player

Career shot-level profile from the Match Charting Project: serve placement (deuce/ad × wide/body/T), return depth and outcomes, net play, clutch break/game/set-point serving, winners and errors by wing, rally-length tendencies — summed over the player's charted matches. COVERAGE IS CURATED (11,646 charted matches back to the 1960s, concentrated on the majors), not full-slate. An ambiguous name returns the candidates to choose from. Requires the ULTRA plan.

Parameters2

name	string	required	Player name fragment, min 3 chars — must resolve to one charted person.
gender	string	optional	Disambiguates a name charted on both tours.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "minLength": 3,
      "description": "Player name fragment, min 3 chars — must resolve to one charted person."
    },
    "gender": {
      "type": "string",
      "enum": [
        "men",
        "women"
      ],
      "description": "Disambiguates a name charted on both tours."
    }
  },
  "required": [
    "name"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

get_charting_match

Every Match Charting Project 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–2026), mostly matches with no counterpart in the live tables. Requires the ULTRA plan.

Parameters1

charting_match_id

integer

required

Charting match id — its own id space, not a match_id.

Raw schema

{
  "type": "object",
  "properties": {
    "charting_match_id": {
      "type": "integer",
      "description": "Charting match id — its own id space, not a match_id."
    }
  },
  "required": [
    "charting_match_id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

check_api_status

Check whether the Live Tennis API is reachable and which plan the configured key is on. Useful for diagnosing why other tools are refusing data.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

README.md13 KBView on GitHub

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

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

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
`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 shot-level profile from the Match Charting Project	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 our own 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:

code

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 is enforced upstream 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:

code

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 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 + transport isolation + rate limiting
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	—

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.

Install

Tools (24)

get_live_matchesget_upcoming_matchesget_matchget_match_scoresearch_playersget_playerget_fixturessearch_tournaments

Configuration

Environment variables

LIVETENNISAPI_KEYsecret

Your Live Tennis API key (twjp_...). Get one free, no card, at https://livetennisapi.com/subscribe/free — the server runs without it but only the status check will work.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "livetennisapi-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "livetennisapi-mcp@1.5.0"
      ],
      "env": {
        "LIVETENNISAPI_KEY": "<YOUR_LIVETENNISAPI_KEY>"
      }
    }
  }
}

LiveTennisAPI MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

get_live_matches

get_upcoming_matches

get_match

get_match_score

search_players

get_player

get_fixtures

search_tournaments

get_tournament

get_recent_results

search_archive_matches

get_archive_match

search_archive_players

get_archive_career

get_h2h

get_match_events

get_match_odds

get_rankings

get_match_analysis

get_player_rankings

get_match_statistics

get_charting_player

get_charting_match

check_api_status

livetennisapi-mcp

Setup

Try it

Tools

Tier awareness

Plans

Request quotas

Hosted endpoint

Use with Claude

Use with Codex

Bundled skill: Polymarket / Kalshi tennis trading data

Notes

Development

Related

Affiliate program

Licence

Install

Configuration

Related servers