🎾 tennis-mcp

Zero-clone Model Context Protocol (MCP) server for Open Era ATP tennis.

Query 200,105 ATP matches (1968–2026), 7,622 player careers, 113,744 surface-split head-to-heads, 7,663 Match Charting Project shot/rally breakdowns, and curated dominance/drama indices (GSDI, NBI, Race to Greatness, Young Guns) directly inside Claude, Cursor, Antigravity, or VS Code — without cloning the 265 MB data repo.

⚡ Quick Start (Zero Clone)

tennis-mcp runs via uvx (or pip) and lazily caches only the Parquet/JSON tables your questions need into ~/.cache/tennis-mcp/.

Claude Desktop / Cursor / Antigravity (mcpServers)

{
  "mcpServers": {
    "tennis-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sorukumar/tennis-mcp",
        "tennis-mcp"
      ]
    }
  }
}

Claude Code (CLI)

claude mcp add tennis-mcp -- uvx --from git+https://github.com/sorukumar/tennis-mcp tennis-mcp

VS Code (.vscode/mcp.json)

{
  "servers": {
    "tennis-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/sorukumar/tennis-mcp",
        "tennis-mcp"
      ]
    }
  }
}

Local Development / Offline tml-data Override

If you already cloned sorukumar/tml-data, point TML_DATA_DIR at it to skip HTTPS downloads completely:

pip install -e ".[dev]"
TML_DATA_DIR=/path/to/tml-data/data tennis-mcp

🛠 Available MCP Capabilities

15 Tools (Powered by DuckDB + Parquet + Story JSONs)

7 Resources (tennis://*)

• tennis://overview, tennis://gsdi/top, tennis://nbi/top, tennis://greatness/summary, tennis://young-guns/summary, tennis://global/timeline, tennis://indian/notable

3 Prompt Templates

• scouting_report(player_name)
• rivalry_breakdown(player1, player2)
• slam_campaign_audit(player_name, tournament)

💬 Example Questions You Can Ask Your AI

• "Compare Jannik Sinner and Carlos Alcaraz on 1st-serve won%, unforced error rate, and Clay charting metrics."
• "Show me Novak Djokovic vs Rafael Nadal head-to-head by surface, plus their highest Nail-Biter Index Slam matches."
• "Which players won a Grand Slam with the fewest tour matches before their first major?"
• "How does Joao Fonseca at age 18–20 track against Carlos Alcaraz in ATP wins and Top 50 wins?"
• "List the top 5 Grass-court Grand Slam comebacks since 2000 sorted by comeback score and duration."

🏗 Architecture

Claude / Cursor / Antigravity / VS Code
            │  (stdio MCP)
            ▼
       tennis-mcp  (Python + FastMCP/MCPServer + DuckDB)
            │
            ├── TML_DATA_DIR set? ──▶ Local tml-data/data/*.parquet + *.json
            │
            └── Otherwise ──────────▶ Lazy cache (~/.cache/tennis-mcp/, 7-day TTL)
                                       fetched via HTTPS from sorukumar/tml-data

📄 License & Data Attribution

• Code: MIT License (LICENSE)
• ATP Match & Career Warehouse (sorukumar/tml-data): Built on Tennismylife / TML-Database and Jeff Sackmann's ATP archive (MIT).
• Match Charting Project Tables (mcp_*.parquet): Derived from Jeff Sackmann's Match Charting Project, licensed under CC BY-NC-SA 4.0 (attribution required; non-commercial share-alike for charting tables).