CLI & MCP Server

SportsStack publishes @sportsstack/mcp-server — a combined CLI and MCP (Model Context Protocol) server that gives both humans and AI agents access to live sports data. One package, two interfaces.

Both modes use the same 19 tools, same authentication, and same API.

Quick Start — CLI

# No install needed
npx -y @sportsstack/mcp-server --cli schedule --league NBA

# Or install globally
npm install -g @sportsstack/mcp-server
sportsstack schedule --league NBA --date 2026-02-25

Output is JSON by default. Add --summary for human-readable text:

sportsstack schedule --league NFL --summary

List all commands:

sportsstack --help

Describe a specific command (machine-readable, useful for agents):

sportsstack describe schedule

Quick Start — MCP

npx -y @sportsstack/mcp-server

No build step, no cloning — one command installs and runs the MCP server on STDIO.

Setup by Client

Claude Desktop / Claude Code

Add to your MCP settings (~/.claude/settings/claude_desktop_config.json or the app's settings UI):

{
  "mcpServers": {
    "sportsstack": {
      "command": "npx",
      "args": ["-y", "@sportsstack/mcp-server"],
      "env": {
        "SPORTSSTACK_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Restart Claude, then ask: "What NFL games are on this week?"

Cursor

Add to .cursor/mcp.json in your project root (or global Cursor settings):

{
  "mcpServers": {
    "sportsstack": {
      "command": "npx",
      "args": ["-y", "@sportsstack/mcp-server"],
      "env": {
        "SPORTSSTACK_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP configuration:

{
  "mcpServers": {
    "sportsstack": {
      "command": "npx",
      "args": ["-y", "@sportsstack/mcp-server"],
      "env": {
        "SPORTSSTACK_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

Gemini CLI

SPORTSSTACK_API_KEY=YOUR_API_KEY npx -y @sportsstack/mcp-server

Any MCP-Compatible Client

The server uses STDIO transport (JSON-RPC 2.0 over stdin/stdout), which is supported by all MCP clients. Point your client at npx -y @sportsstack/mcp-server with the SPORTSSTACK_API_KEY environment variable.

Authentication

Set the SPORTSSTACK_API_KEY environment variable to your API key.

For CLI: export SPORTSSTACK_API_KEY=your-key or pass inline (SPORTSSTACK_API_KEY=key sportsstack ...).

Get an API key from Dashboard → Settings → API Keys, or see the Authentication guide.

Available Tools

Every tool is available as both an MCP tool (for agents) and a CLI command (for humans).

Discovery

Scores & Schedule

Standings & Stats

Teams & Players

Betting & Injuries

Entity Mappings & ID Translation

Cross-reference entity IDs across data providers (SportRadar, ESPN, SportsDataIO, OddsBlaze, etc.).

Note: id-search, id-translate, and id-resolve require the id_explorer feature flag to be enabled for your API key. mappings is always available.

Mapping CLI Examples

# Find all ESPN mappings for NBA events
sportsstack mappings --entity-type event --league NBA --integration espn

# See all provider IDs for a single entity
sportsstack mappings --common-model-id <uuid> --include-all-mappings

# Search by source ID
sportsstack id-search --query "sr:sport_event:62925271"

# Translate: given a common_model_id, find the ESPN source ID
sportsstack id-translate --entity-id <uuid> --from-provider sportradar --to-provider espn

# Resolve: see every provider mapping for an entity
sportsstack id-resolve --entity-id <uuid>

Mapping Workflow

The translate and resolve tools operate on common_model_id (the canonical SportsStack UUID), not provider source IDs. Typical workflow:

1. Find the entity — use mappings or id-search to locate a mapping by source ID
2. Get the common_model_id — from the mapping result
3. Translate or resolve — use id-translate or id-resolve with the common_model_id

Or ask your AI agent: "What's the ESPN ID for SportRadar event sr:sport_event:62925271?" — it chains the calls for you.

Example Conversations

MCP (AI Agent)

Once connected, try asking your AI agent:

CLI (Human)

# Multi-step workflow in the shell
EVENT_ID=$(sportsstack schedule --league NBA --date 2026-02-25 | jq -r '.data[0].common_model_id')
sportsstack odds --event $EVENT_ID
sportsstack mappings --common-model-id $EVENT_ID --include-all-mappings

Fuzzy Name Resolution

You don't need IDs to query — the MCP server and CLI accept human-readable names and resolve them automatically:

• League names: "NFL", "nfl", "National Football League" all work
• Team names: "Chiefs", "KC", "Kansas City" all resolve to the same team
• Player names: "LeBron", "LBJ", "King James" all find LeBron James
• Nicknames: "Niners" → 49ers, "Pats" → Patriots, "ManU" → Manchester United

When a name is ambiguous (e.g., "Giants" matches both NFL and MLB), the server returns candidates and asks for clarification.

Supported Leagues

Use get_sports_list / sportsstack sports to see the full list. Major leagues include:

• Football: NFL, NCAAF
• Basketball: NBA, NCAAB, WNBA
• Baseball: MLB
• Hockey: NHL
• Soccer: EPL, MLS, Champions League
• Golf: PGA Tour

Rate Limits

The same rate limits apply as the REST API. Rate limit headers are tracked automatically — the server backs off when limits are approached.

Architecture

CLI:       [Terminal] → sportsstack <command> → [Tool Handler] → HTTPS → [SportsStack REST API]
MCP:  [AI Agent] → JSON-RPC (STDIO) → [MCP Server] → [Tool Handler] → HTTPS → [SportsStack REST API]

The CLI and MCP server share the same tool handlers. The MCP server adds a thin JSON-RPC 2.0 transport layer; the CLI adds argument parsing and stdout output.

No data is stored locally. All data comes from the live SportsStack API.

Discovery Endpoints

SportsStack also exposes machine-readable discovery files for LLM agents that connect directly to the API:

• /mcp.json — MCP discovery document listing all API resources
• /.well-known/mcp.json — Standard MCP discovery location
• /llms.txt — Human-readable instructions for LLM agents
• /openapi — Full OpenAPI 3.0 specification

Requirements

• Node.js 18 or later
• npm (included with Node.js)

Troubleshooting

Server won't start: Make sure Node.js 18+ is installed (node --version).

Auth errors: Check that SPORTSSTACK_API_KEY is set correctly. For MCP: check the env block in your client config. For CLI: echo $SPORTSSTACK_API_KEY.

No results: Most tools require a league parameter. Try specifying the league explicitly (e.g., --league NBA).

ID Explorer returns 403: The id_explorer feature flag must be enabled for your API key. Contact support to enable it.

Rate limited: The server automatically retries on rate limits with exponential backoff. If you're hitting limits frequently, consider upgrading your plan.

Next Steps

• Getting Started — REST API quickstart
• Authentication — API keys and security
• API Usage Guide — Deep dive into the data model
• Coverage Matrix — Full sport and league coverage