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 TD
    Client["AI Agent / MCP Client<br>(Antigravity, Claude, Codex, Cortex)"]
    Gateway["Root FastMCP Gateway (espn-mcp)<br>(stdio / Streamable HTTP)"]
    ParentMW["Parent Middleware Pipeline<br>(ParentAuditMiddleware & ReadOnlyGateMiddleware)"]
    GamesSub["Sub-Server: espn-games<br>(games_* | GamesDomainGuard)"]
    TeamsSub["Sub-Server: espn-teams<br>(teams_* | TeamsDomainGuard)"]
    NewsSub["Sub-Server: espn-news<br>(news_* | Resources)"]
    ClientHandler["Hardened ESPN AsyncClient<br>(Connection Pool & 429 Jitter Backoff)"]
    ESPN["ESPN Public REST CDN<br>(https://site.web.api.espn.com)"]

    Client <-->|"JSON-RPC (tools/list, tools/call)"| Gateway
    Gateway --> ParentMW
    ParentMW --> GamesSub
    ParentMW --> TeamsSub
    ParentMW --> NewsSub
    GamesSub & TeamsSub & NewsSub <-->|"API Methods"| ClientHandler
    ClientHandler <-->|"HTTPS REST Mirror"| ESPN

🚀 FastMCP 4 Server Composition

mcp-server-espn implements canonical FastMCP 4 Server Composition via root.mount(..., namespace="..."):

• Domain Sub-Servers: Partitioned into espn-games (games_*), espn-teams (teams_*), and espn-news (news_*).
• Hierarchical Middleware:
  • Parent: ParentAuditMiddleware (timing logs, audit trails, and secret scrubbing) and ReadOnlyGateMiddleware (fail-closed read-only enforcement).
  • Child: GamesDomainGuardMiddleware (query limit validation <= 100) and TeamsDomainGuardMiddleware (team and athlete identifier validation).
• Focused Profiles: Run lightweight surfaces via --profile full|games|teams|news|readonly (ESPN_MCP_PROFILE):
  • full (default): All 33 domain tools and resources mounted.
  • games: Scores, summaries, schedules, standings, rankings, transactions, league leaders, draft, live play-by-play, situations, odds, probabilities, predictor, calendar, futures, power index (20 tools).
  • teams: Rosters, depth charts, player stats, athlete profiles, bio, stats, gamelog, splits, search, list teams, team detail, team statistics (12 tools).
  • news: League news and reference resources (1 tool).
  • readonly: Read-only enforcement across all routes.
• Opt-In Tool Search: Preserves standard flat tools/list by default for seamless client compatibility, while enabling search transforms via --enable-tool-search (ESPN_MCP_ENABLE_TOOL_SEARCH): BM25 ranking for natural-language queries by default (search_tools takes a query), or regex patterns with --tool-search-backend regex (ESPN_MCP_TOOL_SEARCH_BACKEND=regex; search_tools takes a pattern).

📈 Sports Intelligence Workflows

Workflow 1: Live In-Game Win Probability & Situation Tracking

1. Poll Active Games: Agent calls games_get_scoreboard(sport="football", league="nfl") to identify close games in the 2nd half.
2. Fetch In-Game Situation & Win Probability: Call games_get_game_situation(sport="football", league="nfl", event_id="401872947") and games_get_win_probabilities(sport="football", league="nfl", event_id="401872947") to inspect down/distance, red zone state, and live win expectancy curve.
3. Inspect Play-by-Play: Call games_get_play_by_play(sport="football", league="nfl", event_id="401872947") for drive-by-drive sequencing and scoring event logs.

Workflow 2: Athlete Deep Dive & Fantasy Valuation

1. Bio & Career Context: Call teams_get_athlete_bio(sport="football", league="nfl", athlete_id="12483") to retrieve draft capital, college pedigree, and physical metrics.
2. Recent Gamelog & Splits: Pull teams_get_athlete_gamelog and teams_get_athlete_splits to analyze performance trends against specific defensive schemes and venue conditions.
3. League-Wide Leaderboard Standing: Call games_get_leaders_by_athlete(sport="football", league="nfl", category="passing", sort="yards") to evaluate percentile rankings.

🏟️ Supported Sports & Leagues Reference Matrix

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

📊 Tool Suite (33 Domain Tools)

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

🏃 Quickstart & Installation

1. Run Directly via uvx (Zero Install)

Console scripts in [project.scripts] both call espn_mcp.server:main: espn-mcp (used below) and mcp-server-espn. Install examples stay unpinned. To freeze a release, pin the version from Releases.

uvx --from mcp-server-espn espn-mcp

After an upgrade, reload the MCP host so the live process start time is after the new binary mtime (stale process ≠ new package).

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

🧡 Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

For Claude Code CLI:

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

♊ Google Antigravity & Gemini CLI

Add to .agents/mcp_config.json or ~/.gemini/config/mcp_config.json:

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

❄️ Snowflake Cortex

Add to ~/.snowflake/cortex/mcp.json:

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

⚡ Cursor IDE

Add to .cursor/mcp.json:

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

💻 VS Code (Cline / Roo Code / Copilot Agent Mode)

Add to cline_mcp_settings.json or .vscode/settings.json:

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

🌐 Local HTTP / Network Transport Mode

Launch the FastMCP server over modern Streamable HTTP:

uvx --from mcp-server-espn espn-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Connect Streamable HTTP clients to http://127.0.0.1:8000/mcp (FastMCP's default Streamable HTTP path).

In the default (stateful) HTTP mode, a session idle for 30 minutes expires: its next request gets HTTP 404 and the client must start a new session. Change this with FastMCP's session_idle_timeout (on http_app()) or FASTMCP_HTTP_SESSION_IDLE_TIMEOUT (seconds, or none to never expire); see the FastMCP 4.1.0 release and #5229.

HTTP authentication. Set ESPN_MCP_AUTH_TOKEN to require Authorization: Bearer <token> on every HTTP request; a missing or wrong token gets 401. The token is stripped, and a blank value counts as unset. It is attached when the server is built, so espn-mcp, fastmcp run and an ASGI host mounting mcp.http_app() all enforce it. stdio never uses it.

With no token, espn-mcp refuses an HTTP bind to any host other than 127.0.0.1, ::1 or localhost and exits with code 2. Set the token, bind to localhost, or set ESPN_MCP_ALLOW_UNAUTHENTICATED_BIND=1 to accept an unauthenticated public bind. Other entry points get the token but not the localhost check: fastmcp run and http_app() do not go through espn-mcp's main(), so a bind to 0.0.0.0 with no token there is not refused and serves without authentication. The host or its process manager owns the bind address, so set ESPN_MCP_AUTH_TOKEN there.

To serve the image over HTTP, pass the token from your shell or an env file (never a fixed value) and name the public host clients use:

PUBLIC_HOST=mcp.example.com   # the host name clients use
export ESPN_MCP_AUTH_TOKEN="$(openssl rand -hex 32)"   # or keep it in an env file
docker run --rm -p 8000:8000 -e ESPN_MCP_AUTH_TOKEN \
  ghcr.io/christianclaudio/mcp-server-espn:latest \
  --transport streamable-http --host 0.0.0.0 --allowed-host "$PUBLIC_HOST"
# with an env file instead: docker run --rm -p 8000:8000 --env-file espn.env ...

📚 Canonical Documentation & Live Doc MCPs

When developing, hardening, or extending MCP servers, consult the official framework and protocol references:

• FastMCP 4 Framework Reference: https://gofastmcp.com/llms.txt — Server composition (mount), hierarchical middleware, transforms (ToolTransform, ToolSearch), lifespans, and in-memory test clients.
• Model Context Protocol Specification: https://modelcontextprotocol.io/llms.txt — Official Spec (2026-07-28), wire-level JSON-RPC schemas, annotations, and transport framing.

Live Documentation MCP Endpoints (SSE / Streamable HTTP)

Connect your AI coding agent directly to live documentation servers:

• FastMCP Documentation Server: https://gofastmcp.com/mcp (Tools: search_fast_mcp, query_docs_filesystem_fast_mcp, submit_feedback)
• Anthropic MCP Documentation Server: https://modelcontextprotocol.io/mcp (Tools: search_model_context_protocol, query_docs_filesystem_model_context_protocol, submit_feedback)

{
  "mcpServers": {
    "fastmcp-docs": { "type": "sse", "url": "https://gofastmcp.com/mcp" },
    "mcp-official-docs": { "type": "sse", "url": "https://modelcontextprotocol.io/mcp" }
  }
}

🏆 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 & protocol conformance audits
python scripts/check_tool_contract.py
python scripts/check_openapi_drift.py
./scripts/check_conformance.sh

📜 License

Distributed under the Apache-2.0 License.