livetennisapi-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Live Tennis API
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/livetennisapi/.github/main/profile/banner.jpg" alt="Live Tennis API" width="640">
+
+# livetennisapi-mcp
+
+**MCP server for the [Live Tennis API](https://livetennisapi.com).**
+
+Give Claude, Cursor, Zed or any MCP client live tennis scores, players, odds
+and model win-probability — for ATP, WTA, Challenger and ITF.
+
+[![npm](https://img.shields.io/npm/v/livetennisapi-mcp.svg)](https://www.npmjs.com/package/livetennisapi-mcp)
+[![license](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[**Documentation**](https://docs.livetennisapi.com) · [**Get an API key**](https://livetennisapi.com/#pricing)
+
+</div>
+
+---
+
+## 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 key at [livetennisapi.com](https://livetennisapi.com/#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 | BASIC |
+| `get_upcoming_matches` | Matches starting soon | BASIC |
+| `get_match` | Full detail for one match | BASIC |
+| `get_match_score` | Current score only — fastest read | BASIC |
+| `search_players` | Find players by name | BASIC |
+| `get_player` | Profile, ranking, country, handedness | BASIC |
+| `get_fixtures` | Forward schedule | BASIC |
+| `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 | — | — | ✅ |
+
+## Notes
+
+- **Read-only.** Every tool is a GET; nothing here can modify anything.
+- **Your key stays local.** It is read from the environment by the server
+  process on your machine and sent only to `api.livetennisapi.com`.
+- Requires Node 18+.
+
+## Development
+
+```bash
+npm install
+npm run build
+LIVETENNISAPI_KEY=twjp_… node dist/index.js   # speaks MCP over stdio
+```
+
+Built on the official [`livetennisapi`](https://www.npmjs.com/package/livetennisapi)
+client.
+
+## Licence
+
+MIT — see [LICENSE](LICENSE). Use of the API service is governed by the
+[Terms of Service](https://livetennisapi.com/terms).

package/dist/index.js

@@ -0,0 +1,315 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  LiveTennisAPI,
+  NotFound,
+  RateLimited,
+  Unauthorized,
+  UpgradeRequired,
+  formatScore
+} from "livetennisapi";
+import { z } from "zod";
+var VERSION = "1.0.0";
+var apiKey = (process.env.LIVETENNISAPI_KEY ?? "").trim();
+var client = new LiveTennisAPI({
+  apiKey,
+  baseUrl: process.env.LIVETENNISAPI_BASE_URL
+});
+var text = (body) => ({ content: [{ type: "text", text: body }] });
+async function guard(run) {
+  if (!apiKey) {
+    return text(
+      "No API key configured. Set the LIVETENNISAPI_KEY environment variable in your MCP client config. Get a key at https://livetennisapi.com/#pricing"
+    );
+  }
+  try {
+    return text(await run());
+  } catch (err) {
+    if (err instanceof UpgradeRequired) {
+      return text(
+        `This data requires the ${err.requiredTier ?? "a higher"} plan, and the configured API key is on a lower tier. Nothing is wrong with the key \u2014 the endpoint is simply not included in the current plan. Upgrade at https://livetennisapi.com/#pricing
+
+Tiers: BASIC = matches, scores, players, fixtures, history \xB7 PRO = + match events and market prices \xB7 ULTRA = + model analysis, win probability and the live WebSocket feed.`
+      );
+    }
+    if (err instanceof Unauthorized) {
+      return text(
+        "The API key was rejected \u2014 it is missing, unknown, or disabled. Check LIVETENNISAPI_KEY in your MCP client config. Keys are at https://livetennisapi.com"
+      );
+    }
+    if (err instanceof NotFound) {
+      return text("No data found for that request. The id may be wrong, or there may be no data yet.");
+    }
+    if (err instanceof RateLimited) {
+      const wait = err.retryAfter ? ` Retry in about ${err.retryAfter}s.` : "";
+      return text(`Rate limit reached for this plan.${wait}`);
+    }
+    return { ...text(`Request failed: ${err instanceof Error ? err.message : String(err)}`), isError: true };
+  }
+}
+function summarise(match) {
+  const p1 = match.players?.p1?.name ?? "?";
+  const p2 = match.players?.p2?.name ?? "?";
+  const serving = match.score?.server === 1 ? " (serving)" : "";
+  const serving2 = match.score?.server === 2 ? " (serving)" : "";
+  const bits = [
+    `[${match.id}] ${match.tournament ?? "Unknown event"}${match.round ? ` \u2014 ${match.round}` : ""}`,
+    `  ${p1}${serving} vs ${p2}${serving2}`,
+    `  Score: ${formatScore(match.score)}`
+  ];
+  if (match.surface) bits.push(`  Surface: ${match.surface}${match.indoor ? " (indoor)" : ""}`);
+  if (match.status && match.status !== "live") bits.push(`  Status: ${match.status}`);
+  if (match.winner) bits.push(`  Winner: ${match.winner === 1 ? p1 : p2}`);
+  if (match.score?.win_probability_p1 != null) {
+    bits.push(`  Model win probability (${p1}): ${(match.score.win_probability_p1 * 100).toFixed(1)}%`);
+  }
+  return bits.join("\n");
+}
+var server = new McpServer({ name: "livetennisapi", version: VERSION });
+server.tool(
+  "get_live_matches",
+  'List tennis matches currently in progress, with live scores. Covers ATP, WTA, Challenger and ITF. Use this for "what tennis is on right now".',
+  { limit: z.number().int().min(1).max(200).default(20).describe("Maximum matches to return") },
+  ({ limit }) => guard(async () => {
+    const page = await client.listMatches({ status: "live", limit });
+    if (!page.data.length) return "No matches are live right now.";
+    return `${page.data.length} live match(es):
+
+${page.data.map(summarise).join("\n\n")}`;
+  })
+);
+server.tool(
+  "get_upcoming_matches",
+  "List tennis matches scheduled to start soon, with players and tournament.",
+  { limit: z.number().int().min(1).max(200).default(20) },
+  ({ limit }) => guard(async () => {
+    const page = await client.listMatches({ status: "upcoming", limit });
+    if (!page.data.length) return "No upcoming matches are scheduled.";
+    return `${page.data.length} upcoming match(es):
+
+${page.data.map(summarise).join("\n\n")}`;
+  })
+);
+server.tool(
+  "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.",
+  { match_id: z.number().int().describe("Match id, from get_live_matches or search") },
+  ({ match_id }) => guard(async () => {
+    const match = await client.getMatch(match_id);
+    let out = summarise(match);
+    if (match.market) {
+      out += `
+
+Market: ${match.market.question ?? "-"}`;
+      for (const price of match.market.prices ?? []) {
+        out += `
+  Side ${price.side}: mid ${price.mid ?? "-"} (bid ${price.bid ?? "-"} / ask ${price.ask ?? "-"})`;
+      }
+    }
+    if (match.analysis?.profile) {
+      const profile = match.analysis.profile;
+      out += `
+
+Model analysis:`;
+      if (profile.win_probability_p1 != null) {
+        out += `
+  Win probability (player 1): ${(profile.win_probability_p1 * 100).toFixed(1)}%`;
+      }
+      if (profile.key_factors?.length) out += `
+  Key factors: ${profile.key_factors.join("; ")}`;
+    }
+    return out;
+  })
+);
+server.tool(
+  "get_match_score",
+  "Current score for one match \u2014 the fastest, lowest-latency read. Use this when you only need the score and already know the match id.",
+  { match_id: z.number().int() },
+  ({ match_id }) => guard(async () => {
+    const score = await client.getMatchScore(match_id);
+    const parts = [`Score: ${formatScore(score)}`];
+    if (score.sets) parts.push(`Sets: ${score.sets.join("-")}`);
+    if (score.server) parts.push(`Serving: player ${score.server}`);
+    if (score.is_tiebreak) parts.push("In a tiebreak");
+    if (score.win_probability_p1 != null) {
+      parts.push(`Model win probability (player 1): ${(score.win_probability_p1 * 100).toFixed(1)}%`);
+    }
+    return parts.join("\n");
+  })
+);
+server.tool(
+  "search_players",
+  "Search tennis players by name. Returns id, country, ranking and tour. Use the returned id with get_player.",
+  {
+    query: z.string().min(1).describe('Full or partial player name, e.g. "alcaraz"'),
+    limit: z.number().int().min(1).max(200).default(10)
+  },
+  ({ query, limit }) => guard(async () => {
+    const page = await client.searchPlayers(query, { limit });
+    if (!page.data.length) return `No players matched "${query}".`;
+    return page.data.map(
+      (p) => `[${p.id}] ${p.name ?? "?"}${p.country ? ` (${p.country})` : ""}${p.ranking != null ? ` \u2014 rank ${p.ranking}` : ""}${p.tour ? ` \xB7 ${p.tour}` : ""}`
+    ).join("\n");
+  })
+);
+server.tool(
+  "get_player",
+  "One player's profile: ranking, country, handedness, date of birth and cached stats.",
+  { player_id: z.number().int().describe("Player id, from search_players") },
+  ({ player_id }) => guard(async () => {
+    const p = await client.getPlayer(player_id);
+    const rows = [
+      `${p.name ?? "Unknown"} [${p.id}]`,
+      p.country ? `Country: ${p.country}` : null,
+      p.ranking != null ? `Ranking: ${p.ranking}${p.ranking_points ? ` (${p.ranking_points} pts)` : ""}` : null,
+      p.ranking_movement ? `Movement: ${p.ranking_movement}` : null,
+      p.hand ? `Plays: ${p.hand === "R" ? "right-handed" : "left-handed"}` : null,
+      p.birthday ? `Born: ${p.birthday}` : null,
+      p.tour ? `Tour: ${p.tour}` : null
+    ].filter(Boolean);
+    return rows.join("\n");
+  })
+);
+server.tool(
+  "get_fixtures",
+  "Upcoming scheduled tennis fixtures, earliest first \u2014 the forward schedule.",
+  { limit: z.number().int().min(1).max(200).default(20) },
+  ({ limit }) => guard(async () => {
+    const page = await client.listFixtures({ limit });
+    if (!page.data.length) return "No upcoming fixtures.";
+    return page.data.map(
+      (f) => `${f.event_date ?? "?"} \u2014 ${f.tournament ?? "?"}${f.round ? ` (${f.round})` : ""}: ${f.player1_name ?? "?"} vs ${f.player2_name ?? "?"}`
+    ).join("\n");
+  })
+);
+server.tool(
+  "get_recent_results",
+  "Recently completed tennis matches with final scores and winners.",
+  { limit: z.number().int().min(1).max(200).default(20) },
+  ({ limit }) => guard(async () => {
+    const page = await client.listCompletedMatches({ limit });
+    if (!page.data.length) return "No completed matches available.";
+    return page.data.map(summarise).join("\n\n");
+  })
+);
+server.tool(
+  "get_match_events",
+  "Timeline of events for a match \u2014 breaks, games won, sets won, momentum runs. Requires the PRO plan.",
+  { match_id: z.number().int(), limit: z.number().int().min(1).max(200).default(30) },
+  ({ match_id, limit }) => guard(async () => {
+    const page = await client.listMatchEvents(match_id, { limit });
+    if (!page.data.length) return "No events recorded for this match.";
+    return page.data.map((e) => `${e.timestamp ?? "?"} \u2014 ${e.type ?? "?"}${e.player ? ` (player ${e.player})` : ""}`).join("\n");
+  })
+);
+server.tool(
+  "get_match_odds",
+  "Match-winner market prices for a match \u2014 implied probability per player, with bid, ask and mid. Requires the PRO plan.",
+  { match_id: z.number().int(), limit: z.number().int().min(1).max(200).default(10) },
+  ({ match_id, limit }) => guard(async () => {
+    const market = await client.getMarketPrices(match_id, { limit });
+    const lines = [`Market: ${market.question ?? "-"}`];
+    if (market.status) lines.push(`Status: ${market.status}`);
+    if (market.volume != null) lines.push(`24h volume: ${market.volume}`);
+    if (market.liquidity != null) lines.push(`Liquidity: ${market.liquidity}`);
+    lines.push("", "Recent prices (newest first):");
+    for (const p of market.prices ?? []) {
+      lines.push(
+        `  side ${p.side}: mid ${p.mid ?? "-"} \xB7 bid ${p.bid ?? "-"} \xB7 ask ${p.ask ?? "-"}${p.timestamp ? ` @ ${p.timestamp}` : ""}`
+      );
+    }
+    return lines.join("\n");
+  })
+);
+server.tool(
+  "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.",
+  { match_id: z.number().int() },
+  ({ match_id }) => guard(async () => {
+    const analysis = await client.getMatchAnalysis(match_id);
+    if (!analysis.thesis && !analysis.profile) return "No model analysis exists for this match yet.";
+    const lines = [];
+    if (analysis.profile) {
+      const p = analysis.profile;
+      lines.push("Profile:");
+      if (p.win_probability_p1 != null) {
+        lines.push(`  Win probability (player 1): ${(p.win_probability_p1 * 100).toFixed(1)}%`);
+      }
+      if (p.expected_closeness != null) lines.push(`  Expected closeness: ${p.expected_closeness}`);
+      if (p.volatility_rating) lines.push(`  Volatility: ${p.volatility_rating}`);
+      if (p.key_factors?.length) lines.push(`  Key factors: ${p.key_factors.join("; ")}`);
+    }
+    if (analysis.thesis) {
+      const t = analysis.thesis;
+      lines.push("", "Thesis:");
+      if (t.pick_side) lines.push(`  Pick: player ${t.pick_side}`);
+      if (t.confidence != null) lines.push(`  Confidence: ${(t.confidence * 100).toFixed(0)}%`);
+      if (t.state) lines.push(`  State: ${t.state}`);
+      if (t.reasoning) lines.push(`  Reasoning: ${t.reasoning}`);
+    }
+    return lines.join("\n");
+  })
+);
+server.tool(
+  "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.",
+  {},
+  async () => {
+    try {
+      const health = await client.health();
+      if (!apiKey) {
+        return text(
+          `API is reachable (status: ${health.status}, version: ${health.version}).
+No API key is configured, so only this check will work. Set LIVETENNISAPI_KEY in your MCP client config \u2014 get a key at https://livetennisapi.com/#pricing`
+        );
+      }
+      let tier = "BASIC";
+      try {
+        await client.listMatches({ status: "completed", limit: 1 });
+      } catch (err) {
+        if (err instanceof Unauthorized) {
+          return text("API is reachable, but the configured key was rejected (unauthorized).");
+        }
+        throw err;
+      }
+      const probe = await client.listCompletedMatches({ limit: 1 });
+      const id = probe.data[0]?.id;
+      if (id != null) {
+        try {
+          await client.listMatchEvents(id, { limit: 1 });
+          tier = "PRO";
+          await client.getMatchAnalysis(id);
+          tier = "ULTRA";
+        } catch (err) {
+          if (!(err instanceof UpgradeRequired) && !(err instanceof NotFound)) throw err;
+          if (err instanceof NotFound && tier === "PRO") tier = "ULTRA";
+        }
+      }
+      return text(
+        `API is reachable (status: ${health.status}, version: ${health.version}).
+The configured key appears to be on the ${tier} plan.
+
+BASIC = matches, scores, players, fixtures, history
+PRO   = + match events and market prices
+ULTRA = + model analysis, win probability and the live feed`
+      );
+    } catch (err) {
+      return {
+        ...text(`Could not reach the API: ${err instanceof Error ? err.message : String(err)}`),
+        isError: true
+      };
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`livetennisapi-mcp ${VERSION} ready${apiKey ? "" : " (no API key configured)"}`);
+}
+main().catch((err) => {
+  console.error("fatal:", err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "livetennisapi-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for the Live Tennis API \u2014 give Claude, Cursor and other LLM agents real-time tennis scores, players, odds and model win-probability.",
+  "keywords": [
+    "mcp",
+    "modelcontextprotocol",
+    "model-context-protocol",
+    "mcp-server",
+    "claude",
+    "llm",
+    "ai-agent",
+    "tennis",
+    "tennis-api",
+    "live-scores",
+    "sports",
+    "sports-api",
+    "sports-data",
+    "atp",
+    "wta"
+  ],
+  "homepage": "https://livetennisapi.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/livetennisapi/livetennisapi-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/livetennisapi/livetennisapi-mcp/issues"
+  },
+  "license": "MIT",
+  "author": "Live Tennis API",
+  "type": "module",
+  "bin": {
+    "livetennisapi-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "livetennisapi": "^1.0.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.5.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}