@cyanheads/sports-mcp-server

Tools

Seven tools organized around what an agent needs — find a team or player, get today's scores, check the schedule, read the standings, or pull full team or player detail:

sports_find_team

Resolve a fuzzy team name to its canonical record across ESPN, MLB StatsAPI, and TheSportsDB.

• Returns full name, league, logo URL, venue, and ESPN/MLB/TheSportsDB cross-reference IDs

• Use before sports_get_scores, sports_get_schedule, sports_get_standings, or sports_get_team to get a valid team_name

• Fuzzy match on display name, abbreviation, or location (e.g. "Mariners", "SEA", "Seattle Seahawks")

sports_find_player

Resolve a player name to their canonical record.

• Multi-sport player search via TheSportsDB

• Optional sport filter to narrow ambiguous names (e.g. "Michael Jordan")

• Returns player ID, full name, current team, position, nationality, birth date, and thumbnail URL

• Use the returned player_id with sports_get_player for full bio detail

sports_get_scores

Live and final scores for a league on a given date.

• Routes NFL/NBA/NHL/soccer → ESPN; MLB → MLB StatsAPI (more authoritative)

• Returns home/away teams, current score, status (scheduled/in-progress/final), period/clock, and UTC start time

• Omit date for today's games; use team_name to filter to one team's game

• Returns games: [], reason: '...' (not an error) when no games are scheduled

sports_get_schedule

Upcoming and past fixtures for a team or league over a date range.

• Fetches full season from ESPN and applies date_from/date_to filtering server-side

• Returns opponent, home/away flag, UTC date/time, venue, and result for completed games

• Omit team_name for the full league calendar; provide it for a single team's fixtures

sports_get_standings

Current standings or league table for a league and season.

• Returns rank, W/L (or points for soccer/NHL), division/conference, streak, and games behind

• Omit season for the current season; pass a YYYY year for historical standings

• NHL uses points system (wins/otLosses/losses); soccer returns points for the league table

sports_get_team

Composite team detail combining multiple source calls.

• Active roster (or squad), last 5 results, next 3 fixtures, venue, and team metadata

• MLB teams use MLB StatsAPI for roster and schedule; all others use ESPN

sports_get_player

Full player profile from TheSportsDB.

• Bio, current team, position, nationality, birth date, height/weight, career description

• Media thumbnail URL for display

• Accepts tsdb:-prefixed IDs (from sports_find_player) or raw numeric TheSportsDB IDs

Related MCP server: Sports Hub MCP Server

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation

• Unified error handling — handlers throw, framework catches, classifies, and formats

• Pluggable auth: none, jwt, oauth

• Swappable storage backends: in-memory, filesystem, Supabase, Cloudflare KV/R2/D1

• Structured logging with optional OpenTelemetry tracing

• STDIO and Streamable HTTP transports

Sports-specific:

• Three keyless sources — ESPN site API, MLB StatsAPI, TheSportsDB (free tier key 3) — no API credentials required

• League routing table internally routes each query to the best source per sport; agents never reference an upstream API

• Normalized output types across all sources — NormalizedGame, NormalizedTeam, NormalizedPlayer, NormalizedStanding — with source provenance on every record

• Graceful degradation — empty scoreboards (off-season, no games) return games: [] with a reason string, not an error

Agent-friendly output:

• Source provenance on every record — source: 'espn' | 'mlbstats' | 'thesportsdb' so agents can reason about data authority

• Structured reason field on empty score responses so agents can explain the result to users

• Cross-source IDs surfaced by sports_find_team — espnId, mlbId, tsdbId — for seamless downstream routing without re-resolving names

Getting started

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "sports": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/sports-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "sports": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/sports-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "sports": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/sports-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.3.0 or higher (or Node.js v24+).

• No API keys required — ESPN and MLB StatsAPI are fully keyless; TheSportsDB ships with a free public test key (3).

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/sports-mcp-server.git

2. Navigate into the directory:

cd sports-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env to override defaults (all optional)

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t sports-mcp-server .
docker run --rm -p 3010:3010 sports-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/sports-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts

• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.