io.github.christianclaudio/espn

🏈 mcp-server-espn

Enterprise-grade Model Context Protocol (MCP) server for live and historical sports analytics, consensus betting odds, and predictions via ESPN.
Equips AI agents with real-time sports intelligence, live win probabilities, in-depth boxscore statistics, roster hierarchies, and matchup analytics.

⚠️ Disclaimers & Fair Use Notice

[!IMPORTANT] Community Project Disclaimer
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.

💡 Why This Exists

Autonomous sports analysis requires high-velocity, structured, and resilient data feeds:

1. Live Game State & Win Probability: Real-time game events (turnovers, scoring plays, pitching changes) shift momentum and expected outcomes dynamically.
2. Key Player Injuries & Depth Chart Swaps: An in-game injury or substitution fundamentally alters team efficiency and tactical matchups.
3. Consensus Odds & Predictive Models: Aggregating consensus sportsbook lines (DraftKings, Caesars, ESPN BET) alongside predictive metrics (FPI, BPI) powers deep statistical game evaluations.

mcp-server-espn provides a unified, hardened Model Context Protocol interface directly to ESPN's public sports data endpoints.

🏟️ System Architecture

graph LR
    Agent["AI Agent / MCP Client<br>(Antigravity, Claude, Hermes)"]
    Server["FastMCP Server<br>(stdio / Streamable HTTP)"]
    ClientHandler["Hardened ESPN AsyncClient<br>(Connection Pool & 429 Jitter Backoff)"]
    ESPN["ESPN Public REST CDN<br>(https://site.web.api.espn.com)"]

    Agent <-->|"JSON-RPC / stdio"| Server
    Server <-->|"Validated Tool Calls"| ClientHandler
    ClientHandler <-->|"HTTPS REST Mirror"| ESPN

📈 Sports Intelligence Workflows

Workflow 1: Live In-Game Win Probability & Injury Impact

1. Poll Active Games: Agent calls get_scoreboard(sport="football", league="nfl") to identify close games in the 2nd half.
2. 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.
3. 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).

Workflow 2: Pre-Game Roster & Depth Chart Matchup Preview

1. Analyze Lineups: Call get_team_depth_chart(sport="baseball", league="mlb", team_id="10") to verify probable starters and positional depth.
2. 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.
3. Compare Consensus Betting Lines: Query get_game_summary to evaluate consensus moneyline and over/under spreads across major sportsbooks.

🏟️ Supported Sports & Leagues Reference Matrix

The server supports canonical sport/league slug pairs and auto-normalizes popular shortcuts:

📊 Tool Suite (10 Domain Tools)

All tools implement explicit MCP 2.0 annotations (readOnlyHint=True, idempotentHint=True):

🏃 Quickstart & Installation

1. Run Directly via uvx (Zero Install)

uvx mcp-server-espn

2. Install via pip or uv

# Using pip
pip install mcp-server-espn

# Using uv
uv add mcp-server-espn

3. Run via Docker

docker run --rm -i ghcr.io/christianclaudio/mcp-server-espn:latest

🎛️ Engine Configuration

🎮 Client Integration Guides

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["mcp-server-espn"],
      "env": {
        "ESPN_TIMEOUT_SECONDS": "20.0"
      }
    }
  }
}

claude mcp add espn -- uvx mcp-server-espn

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["mcp-server-espn"],
      "env": {
        "ESPN_TIMEOUT_SECONDS": "20.0"
      },
      "lazy": true
    }
  }
}

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["mcp-server-espn"]
    }
  }
}

{
  "mcpServers": {
    "espn": {
      "command": "uvx",
      "args": ["mcp-server-espn"]
    }
  }
}

python -m espn_mcp.server --transport streamable-http --host 127.0.0.1 --port 8000

🏆 Verification & Quality Gates

# Run unit test suite (100% statement coverage enforced)
pytest

# Static type safety & formatting
mypy --strict src/
ruff check --fix .
ruff format .

# Tool contract & drift audits
python scripts/check_tool_contract.py
python scripts/check_openapi_drift.py
python scripts/smoke_test.py

📜 License

Distributed under the Apache-2.0 License.