npm package: @sportsmcp/server
Description: MCP server that gives AI assistants access to live sports scores, player stats, betting odds, and historical data
Latest version: 0.1.0

# SportsMCP

Give your AI assistant live sports data.

Ask your AI assistant questions like:

- "What's the score of the Lakers game?"
- "Who won last night's NFL games?"
- "What are the NBA standings?"
- "Is Jayson Tatum injured?"
- "What are the odds for tonight's games?"

SportsMCP is an [MCP server](https://modelcontextprotocol.io) that gives Claude, Cursor, and other AI assistants access to live scores, stats, odds, standings, and more across NFL, NBA, MLB, and NHL.

## Quick Start

No install needed. Run it directly with `npx`:

```sh
npx @sportsmcp/server
```

### Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sportsmcp": {
      "command": "npx",
      "args": ["@sportsmcp/server"]
    }
  }
}
```

### Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "sportsmcp": {
      "command": "npx",
      "args": ["@sportsmcp/server"]
    }
  }
}
```

### With API Keys (for odds data)

```json
{
  "mcpServers": {
    "sportsmcp": {
      "command": "npx",
      "args": ["@sportsmcp/server"],
      "env": {
        "SPORTSMCP_ODDS_API_KEY": "your-odds-api-key",
        "SPORTSMCP_BALLDONTLIE_API_KEY": "your-balldontlie-key"
      }
    }
  }
}
```

## Supported Leagues

| League | Scores | Stats | Standings | Schedule | Odds | Injuries | News |
| --- | --- | --- | --- | --- | --- | --- | --- |
| NFL | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| NBA | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| MLB | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
| NHL | Yes | Yes | Yes | Yes | Yes | Yes | Yes |

## Tools

SportsMCP exposes 10 tools to your AI assistant:

| Tool | Description | Key Parameters |
| --- | --- | --- |
| `get_live_scores` | Current/recent game scores | `league`, `team?`, `date?` |
| `get_team_schedule` | Upcoming and recent games for a team | `team`, `league`, `limit?` |
| `get_player_stats` | Season or career stats for a player | `playerId`, `league`, `season?` |
| `get_standings` | League/conference/division standings | `league`, `season?`, `group?` |
| `get_game_details` | Box score and detailed game info | `gameId`, `league` |
| `get_odds` | Moneyline, spread, and over/under lines | `league`, `eventId?` |
| `search_players` | Find players by name (fuzzy matching) | `query`, `league?` |
| `get_team_roster` | Current roster for a team | `team`, `league` |
| `get_injuries` | Injury report for a team or league | `league`, `team?` |
| `get_news` | Recent sports news headlines | `league`, `team?`, `limit?` |

The `league` parameter accepts flexible input: `"nba"`, `"basketball"`, `"NBA"` all work. Team names accept abbreviations (`"LAL"`), short names (`"Lakers"`), or full names (`"Los Angeles Lakers"`).

## Example Output

When you ask "What are today's NBA scores?", the assistant calls `get_live_scores` and gets back:

```
| Matchup     | Score   | Status     |
| ----------- | ------- | ---------- |
| BOS @ MIL   | 112-108 | Final      |
| LAL @ GSW   | 98-102  | 4th 3:42   |
| NYK @ PHI   | 0-0     | 7:30 PM ET |
```

Each response also includes structured JSON data for programmatic use.

## Configuration

Most features work out of the box with no API keys. Optional keys unlock additional data sources:

| Variable | Required For | Get a Key |
| --- | --- | --- |
| `SPORTSMCP_ODDS_API_KEY` | `get_odds` (betting lines) | [the-odds-api.com](https://the-odds-api.com/) |
| `SPORTSMCP_BALLDONTLIE_API_KEY` | Enhanced NBA player stats | [balldontlie.io](https://www.balldontlie.io/) |

Set these as environment variables or pass them through your MCP client config (see Quick Start above).

### What works without API keys

Scores, standings, schedules, rosters, injuries, news, game details, and player search all work without any API keys.

## Development

```sh
git clone https://github.com/sportsmcp/server.git
cd server
npm install
npm run build
```

### Commands

| Command | Description |
| --- | --- |
| `npm run dev` | Run in development mode with watch |
| `npm run build` | Compile TypeScript |
| `npm test` | Run all tests |
| `npm run test:watch` | Run tests in watch mode |
| `npm run lint` | Run ESLint |
| `npm run typecheck` | Type-check without emitting |
| `npm run inspect` | Open MCP Inspector for manual testing |

### Architecture

Tools never call external APIs directly. All data access goes through provider interfaces (`src/providers/types.ts`), making it easy to swap data sources without touching tool code.

```
src/
  server.ts         -- MCP server setup, registers all 10 tools
  tools/            -- One file per tool (get-live-scores.ts, etc.)
  providers/        -- Data source adapters (ESPN, Odds API, etc.)
  formatters/       -- Markdown and JSON output formatters
  cache/            -- In-memory cache with per-resource TTLs
  utils/            -- Validation, date parsing, error classes
```

### Requirements

- Node.js >= 20

## License

MIT