MCP CPBL Statistics

繁體中文

An MCP server for CPBL (Chinese Professional Baseball League / 中華職棒) statistics, exposing AI-callable tools over Model Context Protocol (MCP).

What This Does

• 10 ready-to-use tools covering team standings, player profiles, batting/pitching stats, game logs, head-to-head matchups, top-5 leaderboards, and game schedules
• MCP server (stdio JSON-RPC 2.0) — plug into Claude Code and start asking about CPBL instantly
• Web scraper — HTML scraping and XHR JSON API calls against cpbl.com.tw
• No-auth public access — No API keys required; CSRF token handling is automatic
• Fixture-based unit tests — Fast offline test suite with saved HTML/JSON fixtures
• Integration tests — Live end-to-end tests against cpbl.com.tw, opt-in via -m integration

Quick Start

Install

pip install mcp-cpbl-statistics

Or with uv:

uv sync

Use with Claude Code

claude mcp add --transport stdio cpbl-statistics -- mcp-cpbl-statistics

Use with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "cpbl-statistics": {
      "command": "uv",
      "args": ["run", "mcp-cpbl-statistics"]
    }
  }
}

Or with pip:

{
  "mcpServers": {
    "cpbl-statistics": {
      "command": "mcp-cpbl-statistics"
    }
  }
}

Tools (10)

Standings

Top Lists

Players

Schedule

kind_code values (shared across tools)

Project Structure

mcp-cpbl-statistics/
├── main.py                              # Stub entry point (unused)
├── pyproject.toml                       # Project metadata & scripts
├── .mcp.json                            # Local MCP server config
│
└── src/mcp_cpbl_statistics/
    ├── server.py                        # FastMCP server, registers all tools
    ├── scraper/
    │   └── fetcher.py                   # HTTP client (HTML scraping + JSON POST APIs)
    ├── models/                          # Pydantic output models
    │   ├── standings.py
    │   ├── toplist.py
    │   ├── player.py
    │   ├── apart.py
    │   ├── game_log.py
    │   ├── headtohead.py
    │   ├── schedule.py
    │   └── teams.py                     # Team code registry
    └── tools/                           # MCP tool implementations
        ├── standings/                   # get_season_standings, get_history_standings
        ├── toplist/                     # get_toplist
        ├── player/                      # search_players, get_player_*, ...
        └── schedule/                    # get_schedule

Testing

Unit tests run against saved HTML/JSON fixtures (no live network calls required):

uv run pytest

Integration tests make live requests to cpbl.com.tw and are excluded by default:

uv run pytest -m integration

Data Source

All data is scraped from the official CPBL website (cpbl.com.tw). No API keys are required. The scraper handles CSRF token extraction automatically for POST-based JSON APIs.

License

MIT