{
  "markdown": "<!-- mcp-name: io.github.christianclaudio/espn -->\n\n# 🏈 mcp-server-espn\n\n[![CI](https://github.com/christianclaudio/mcp-server-espn/actions/workflows/ci.yml/badge.svg)](https://github.com/christianclaudio/mcp-server-espn/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/mcp-server-espn)](https://pypi.org/project/mcp-server-espn/)\n[![Python](https://img.shields.io/pypi/pyversions/mcp-server-espn)](https://pypi.org/project/mcp-server-espn/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen.svg)](https://github.com/christianclaudio/mcp-server-espn)\n[![CodeRabbit Reviews](https://img.shields.io/coderabbit/prs/github/christianclaudio/mcp-server-espn?utm_source=oss&utm_medium=github&utm_campaign=christianclaudio%2Fmcp-server-espn&labelColor=171717&color=FF570A&link=https%3A%2F%2Fcoderabbit.ai&label=CodeRabbit+Reviews)](https://coderabbit.ai)\n\n> **Enterprise-grade Model Context Protocol (MCP) server for live and historical sports analytics, consensus betting odds, and predictions via ESPN.**  \n> Equips AI agents with real-time sports intelligence, live win probabilities, in-depth boxscore statistics, roster hierarchies, and matchup analytics.\n\n---\n\n## ⚠️ Disclaimers & Fair Use Notice\n\n> [!IMPORTANT]\n> **Community Project Disclaimer**  \n> `mcp-server-espn` is an independent open-source community project. It is **not** affiliated with, sponsored by, endorsed by, or supported by ESPN Inc. or The Walt Disney Company. *\"ESPN\"* is a trademark of ESPN Inc. All data provided via ESPN's public REST endpoints is intended for educational, research, and personal non-commercial use.\n\n---\n\n## 💡 Why This Exists\n\nAutonomous sports analysis requires high-velocity, structured, and resilient data feeds:\n1. **Live Game State & Win Probability:** Real-time game events (turnovers, scoring plays, pitching changes) shift momentum and expected outcomes dynamically.\n2. **Key Player Injuries & Depth Chart Swaps:** An in-game injury or substitution fundamentally alters team efficiency and tactical matchups.\n3. **Consensus Odds & Predictive Models:** Aggregating consensus sportsbook lines (DraftKings, Caesars, ESPN BET) alongside predictive metrics (FPI, BPI) powers deep statistical game evaluations.\n\n`mcp-server-espn` provides a unified, hardened Model Context Protocol interface directly to ESPN's public sports data endpoints.\n\n---\n\n## 🏟️ System Architecture\n\n```mermaid\ngraph LR\n    Agent[\"AI Agent / MCP Client<br>(Antigravity, Claude, Hermes)\"]\n    Server[\"FastMCP Server<br>(stdio / Streamable HTTP)\"]\n    ClientHandler[\"Hardened ESPN AsyncClient<br>(Connection Pool & 429 Jitter Backoff)\"]\n    ESPN[\"ESPN Public REST CDN<br>(https://site.web.api.espn.com)\"]\n\n    Agent <-->|\"JSON-RPC / stdio\"| Server\n    Server <-->|\"Validated Tool Calls\"| ClientHandler\n    ClientHandler <-->|\"HTTPS REST Mirror\"| ESPN\n```\n\n---\n\n## 📈 Sports Intelligence Workflows\n\n### Workflow 1: Live In-Game Win Probability & Injury Impact\n1. **Poll Active Games:** Agent calls `get_scoreboard(sport=\"football\", league=\"nfl\")` to identify close games in the 2nd half.\n2. **Fetch Matchup Predictor & Injuries:** Call `get_game_summary(sport=\"football\", league=\"nfl\", event_id=\"401547432\")` to retrieve ESPN's live win probability curve, consensus spread, and active injury reports.\n3. **Inspect Player Boxscore Metrics:** Use `get_player_stats(sport=\"football\", league=\"nfl\", event_id=\"401547432\")` to analyze key individual performances (passing yards, completion rates, defensive stops).\n\n### Workflow 2: Pre-Game Roster & Depth Chart Matchup Preview\n1. **Analyze Lineups:** Call `get_team_depth_chart(sport=\"baseball\", league=\"mlb\", team_id=\"10\")` to verify probable starters and positional depth.\n2. **Review Recent Momentum:** Pull `get_team_schedule(sport=\"baseball\", league=\"mlb\", team_id=\"10\")` and `get_standings(sport=\"baseball\", league=\"mlb\")` to evaluate streaks and divisional standing.\n3. **Compare Consensus Betting Lines:** Query `get_game_summary` to evaluate consensus moneyline and over/under spreads across major sportsbooks.\n\n---\n\n## 🏟️ Supported Sports & Leagues Reference Matrix\n\nThe server supports canonical sport/league slug pairs and auto-normalizes popular shortcuts:\n\n| Sport Slug | League Slug | Recognized Shortcuts / Aliases | Common Display Name |\n| :--- | :--- | :--- | :--- |\n| `football` | `nfl` | `nfl` | National Football League |\n| `football` | `college-football` | `cfb`, `ncaa-football`, `fbs` | NCAA College Football |\n| `basketball` | `nba` | `nba` | National Basketball Association |\n| `basketball` | `mens-college-basketball` | `cbb`, `ncaa-basketball` | NCAA Men's College Basketball |\n| `basketball` | `womens-college-basketball` | `wbb`, `ncaa-womens-basketball` | NCAA Women's Basketball |\n| `basketball` | `wnba` | `wnba` | Women's National Basketball Association |\n| `baseball` | `mlb` | `mlb` | Major League Baseball |\n| `hockey` | `nhl` | `nhl` | National Hockey League |\n| `soccer` | `eng.1` | `epl`, `premier-league` | English Premier League |\n| `soccer` | `usa.1` | `mls` | Major League Soccer |\n| `soccer` | `uefa.champions` | `ucl`, `champions-league` | UEFA Champions League |\n| `soccer` | `esp.1` | `la-liga` | Spanish La Liga |\n| `soccer` | `ita.1` | `serie-a` | Italian Serie A |\n| `soccer` | `ger.1` | `bundesliga` | German Bundesliga |\n| `soccer` | `fra.1` | `ligue-1` | French Ligue 1 |\n\n---\n\n## 📊 Tool Suite (10 Domain Tools)\n\nAll tools implement explicit MCP 2.0 annotations (`readOnlyHint=True`, `idempotentHint=True`):\n\n| Tool | Parameters | Description |\n| :--- | :--- | :--- |\n| `get_scoreboard` | `sport`, `league`, `date`, `week`, `season_type`, `group`, `limit` | Live scores, state (`pre`/`in`/`post`), period/clock, TV broadcasts, starting probables. |\n| `get_game_summary` | `sport`, `league`, `event_id` | Consensus betting lines (DraftKings, Caesars, ESPN BET), matchup predictor, live win probability curve, season head-to-head series, momentum (last 5 games), injuries. |\n| `get_player_stats` | `sport`, `league`, `event_id` | Boxscore statistics for individual athletes (batting, pitching, passing, rushing, receiving, scoring). |\n| `get_standings` | `sport`, `league`, `season` | Division, conference, and overall league standings, win-loss records, games back, and win percentages. |\n| `get_news` | `sport`, `league`, `limit` | Recent news headlines, injury designations, and breaking roster analysis. |\n| `get_rankings` | `sport`, `league` | Top 25 national polls and rankings (AP Top 25, Coaches Poll, College Football Playoff). |\n| `get_team_roster` | `sport`, `league`, `team_id` | Full active roster grouped by position, jersey numbers, experience, and injury status. |\n| `get_team_depth_chart` | `sport`, `league`, `team_id` | Positional starter/backup hierarchy (QB1, QB2, RB1, RB2) to model injury substitution impacts. |\n| `get_team_schedule` | `sport`, `league`, `team_id`, `season` | Full regular season and postseason schedule with historical game results and scores. |\n| `get_athlete_overview` | `sport`, `league`, `athlete_id` | Athlete biographical info, season/career split statistics, recent game logs, next game, and rotowire notes. |\n\n---\n\n## 🏃 Quickstart & Installation\n\n### 1. Run Directly via `uvx` (Zero Install)\n```bash\nuvx mcp-server-espn\n```\n\n### 2. Install via `pip` or `uv`\n```bash\n# Using pip\npip install mcp-server-espn\n\n# Using uv\nuv add mcp-server-espn\n```\n\n### 3. Run via Docker\n```bash\ndocker run --rm -i ghcr.io/christianclaudio/mcp-server-espn:latest\n```\n\n---\n\n## 🎛️ Engine Configuration\n\n| Variable | Default | Description |\n| :--- | :--- | :--- |\n| `ESPN_BASE_URL` | `https://site.web.api.espn.com` | Target ESPN REST CDN base URL (bypasses Akamai TLS filter) |\n| `ESPN_TIMEOUT_SECONDS` | `30.0` | HTTP request timeout in seconds |\n| `ESPN_MAX_RETRIES` | `3` | Maximum retry attempts with jittered exponential backoff |\n| `ESPN_MCP_READONLY` | `0` | Restrict server strictly to read-only inspection tools |\n\n---\n\n## 🎮 Client Integration Guides\n\n<details open>\n<summary><b>🧡 Claude Desktop</b></summary>\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"espn\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-espn\"],\n      \"env\": {\n        \"ESPN_TIMEOUT_SECONDS\": \"20.0\"\n      }\n    }\n  }\n}\n```\n\nFor **Claude Code CLI**:\n```bash\nclaude mcp add espn -- uvx mcp-server-espn\n```\n</details>\n\n<details>\n<summary><b>♊ Google Antigravity & Gemini CLI</b></summary>\n\nAdd to `.agents/mcp_config.json` or `~/.gemini/config/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"espn\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-espn\"],\n      \"env\": {\n        \"ESPN_TIMEOUT_SECONDS\": \"20.0\"\n      },\n      \"lazy\": true\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>⚡ Cursor IDE</b></summary>\n\nAdd to `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"espn\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-espn\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>💻 VS Code (Cline / Roo Code / Copilot Agent Mode)</b></summary>\n\nAdd to `cline_mcp_settings.json` or `.vscode/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"espn\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcp-server-espn\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><b>🌐 Local HTTP / Network Transport Mode</b></summary>\n\nLaunch the FastMCP server over modern Streamable HTTP:\n\n```bash\npython -m espn_mcp.server --transport streamable-http --host 127.0.0.1 --port 8000\n```\n\nConnect your local HTTP client to `http://127.0.0.1:8000/sse`.\n</details>\n\n---\n\n## 🏆 Verification & Quality Gates\n\n```bash\n# Run unit test suite (100% statement coverage enforced)\npytest\n\n# Static type safety & formatting\nmypy --strict src/\nruff check --fix .\nruff format .\n\n# Tool contract & drift audits\npython scripts/check_tool_contract.py\npython scripts/check_openapi_drift.py\npython scripts/smoke_test.py\n```\n\n---\n\n## 📜 License\n\nDistributed under the [Apache-2.0 License](LICENSE).\n\n",
  "bytes": 10152,
  "sha": "4c3942f3dd3325c7e117eef720568a9ce4d8477f5c2c5169e005bc0669cd4b64",
  "repo_slug": "christianclaudio/mcp-server-espn",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_christianclaudio_espn_38da84d7/readme"
}