Live Tennis API MCP

What is Live Tennis API MCP about?

Live Tennis API MCP offers a ready‑to‑use MCP server that exposes the Live Tennis API to AI agents such as Claude, Cursor, Zed, or any other MCP‑compatible client. It delivers live match scores, upcoming fixtures, player profiles, odds, and advanced model‑based win‑probability analyses.

How to use Live Tennis API MCP?

1. Install & run – No local installation required; invoke the server with npx -y livetennisapi-mcp. The command reads the API key from the environment variable LIVETENNISAPI_KEY and starts an stdio‑based MCP server.
2. Configure in an agent – Add a MCP server entry (e.g., in Claude Desktop, Cursor, or Codex) that points to the stdio command or to the hosted HTTP endpoint https://mcp.livetennisapi.com/mcp and passes the same API key as a bearer token.
3. Call tools – Agents can request any of the listed tools (e.g., get_live_matches, get_match_odds, get_match_analysis). Tools that require higher‑tier plans return a plain‑English explanation instead of an error.

Key features of Live Tennis API MCP

• Free tier tools: live matches, upcoming matches, match details, scores, player search, player profile, fixtures, recent results.
• Paid tier tools: match events, odds, model analysis with win probability (PRO and ULTRA plans).
• Tier‑aware responses: clear messages when a request exceeds the current subscription level.
• Multiple access methods: stdio server (key never leaves your machine) and hosted Streamable‑HTTP endpoint.
• Rate limiting: 60 req/min anonymous, 300 req/min keyed; respects upstream quota.
• Node 18+, TypeScript source, full test suite including mutation tests.

Use cases of Live Tennis API MCP

• Chatbot assistants delivering up‑to‑the‑minute tennis scores and betting odds.
• Automated sports analysis pipelines that request model‑based win probabilities for betting or recommendation engines.
• Developer prototyping of LLM tools that need sports data without writing API wrappers.
• Integration with IDE assistants (Cursor, Zed, Codex) to answer user queries about tennis matches while coding.

FAQ from the Live Tennis API MCP

Q: Do I need to install anything? A: No. The server runs via npx -y livetennisapi-mcp, which downloads the package on demand.

Q: How is my API key protected? A: When using the stdio mode the key stays in your local environment and is only sent to api.livetennisapi.com. The hosted HTTP endpoint does not store keys; it creates a per‑request server bound to the presented token.

Q: What plans are required for each tool? A: Tools are labeled in the documentation (FREE, BASIC, PRO, ULTRA). The server returns a plain‑English notice if your key’s tier is insufficient.

Q: Can I self‑host the HTTP server? A: Yes. Run node dist/http.js after building, or follow the scripts in deploy/.

Q: Which Node version is needed? A: Node 18 or newer.

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 and ITF. Odds 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-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.

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?"

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 — fastest read	FREE
search_players	Find players by name	FREE
get_player	Profile, ranking, country, handedness	FREE
get_fixtures	Forward schedule	FREE
get_recent_results	Completed matches and winners	BASIC
get_match_events	Breaks, games, sets, momentum runs	PRO
get_match_odds	Match-winner prices — bid / ask / mid	PRO
get_match_analysis	Model thesis, win probability, key factors	ULTRA
check_api_status	Reachability + which plan your key is on	—

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 at https://livetennisapi.com/#pricing

check_api_status probes upward to report which plan your key is actually on, so you can diagnose that without guessing.

Plans

	BASIC	PRO	ULTRA
Matches, scores, players, fixtures, results	✅	✅	✅
Match events + odds	—	✅	✅
Model analysis + win probability	—	—	✅

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. Rate limited per caller — 60 req/min anonymous, 300 keyed — with your real quota enforced upstream per key and tier.

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.

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

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

Related

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

• API reference — https://docs.livetennisapi.com (plain-HTML version, no JavaScript required)
• OpenAPI 3.1 specification — livetennisapi/openapi
• Website and plans — https://livetennisapi.com

Licence

MIT — see LICENSE. Use of the API service is governed by the Terms of Service.