livetennisapi-mcp

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

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

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

¹ Also unlocked by any History plan, which works on top of a free key.

Request quotas

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

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

• API reference — (plain-HTML version, no JavaScript required)
• OpenAPI 3.1 specification — livetennisapi/openapi
• Free API key — (no card)
• Products —
• Website and plans —
• Discord —
• GitHub org —

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.