# NHL MCP Server

A Model Context Protocol (MCP) server that provides live NHL data and statistics with natural language query capabilities. Access real-time game scores, player stats, team standings, playoff information, and historical comparisons through simple tool calls.

## Features

### 1. Live Game Data
Get real-time scores, game status, period information, and venue details for NHL games.

### 2. Team Statistics
Access comprehensive team standings including wins, losses, points, goals for/against, and goal differentials. Filter by division or conference.

### 3. Player Statistics
Query top players by various categories (points, goals, assists, plus/minus, shots) with detailed performance metrics.

### 4. Schedule Information
Get schedules for specific dates, teams, or the entire league with upcoming and completed games.

### 5. Historical Comparisons
Compare team or league-wide statistics across multiple seasons to identify trends and changes.

### 7. Playoff Bracket
View real-time playoff bracket information including series matchups and results.

### 11. Goalie Statistics
Access goalie-specific metrics including save percentage, GAA, wins, shutouts, and more.

### 12. Team Head-to-Head
Compare two teams' head-to-head record with game-by-game results and season series standings.

### 14. Streak Tracking
Track current winning or losing streaks for any team with last 10 games summary.

### 17. Division/Conference Standings
View standings filtered by specific divisions (Atlantic, Metropolitan, Central, Pacific) or conferences (Eastern, Western).

## Installation

```bash
npm install
npm run build
```

## Usage

### Configure with Claude Desktop

Add to your Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "nhl": {
      "command": "node",
      "args": ["/path/to/nhl-mcp-ts/dist/index.js"]
    }
  }
}
```

### Available Tools

#### `get_live_games`
Get live game scores and status.

**Parameters:**
- `date` (optional): Date in YYYY-MM-DD format (defaults to today)

**Example queries:**
- "What NHL games are on today?"
- "Show me yesterday's scores"
- "Are there any games happening right now?"

#### `get_game_details`
Get detailed play-by-play information for a specific game.

**Parameters:**
- `gameId` (required): The NHL game ID

**Example queries:**
- "Show me details for game 2024020156"
- "What happened in game 2024020156?"

#### `get_standings`
Get current NHL standings.

**Parameters:**
- `date` (optional): Date in YYYY-MM-DD format
- `division` (optional): Filter by division (Atlantic, Metropolitan, Central, Pacific)
- `conference` (optional): Filter by conference (Eastern, Western)

**Example queries:**
- "Show me the current NHL standings"
- "What are the Atlantic division standings?"
- "Show me Eastern conference standings"
- "Who's leading the Metropolitan division?"

#### `get_team_stats`
Get detailed statistics for a specific team.

**Parameters:**
- `teamAbbrev` (required): Team abbreviation (TOR, NYR, BOS, MTL, etc.)
- `season` (optional): Season in format YYYYYYYY (e.g., 20242025)

**Example queries:**
- "Show me the Toronto Maple Leafs stats"
- "How are the Rangers doing this season?"
- "Get Boston Bruins statistics"

#### `get_player_stats`
Get top player statistics.

**Parameters:**
- `category` (optional): Sort by points, goals, assists, plusMinus, shots, shootingPctg
- `limit` (optional): Number of players to return (default 20)
- `season` (optional): Season in format YYYYYYYY

**Example queries:**
- "Who are the top scorers in the NHL?"
- "Show me the top 10 goal scorers"
- "Who has the most assists this season?"
- "Which players have the best plus/minus?"

#### `get_goalie_stats`
Get goalie statistics.

**Parameters:**
- `limit` (optional): Number of goalies to return (default 20)
- `season` (optional): Season in format YYYYYYYY

**Example queries:**
- "Who are the best goalies this season?"
- "Show me top 10 goalies by save percentage"
- "Which goalies have the most shutouts?"

#### `get_schedule`
Get game schedules.

**Parameters:**
- `date` (optional): Date in YYYY-MM-DD format
- `teamAbbrev` (optional): Team abbreviation for team-specific schedule

**Example queries:**
- "When does Toronto play next?"
- "Show me the Maple Leafs schedule"
- "What games are scheduled this week?"

#### `get_playoff_bracket`
Get playoff bracket information.

**Parameters:**
- `season` (optional): Season year (e.g., 2024)

**Example queries:**
- "Show me the playoff bracket"
- "What are the current playoff matchups?"
- "Who's in the Stanley Cup Finals?"

#### `compare_teams`
Compare head-to-head statistics between two teams.

**Parameters:**
- `team1` (required): First team abbreviation
- `team2` (required): Second team abbreviation
- `season` (optional): Season in format YYYYYYYY

**Example queries:**
- "How do the Maple Leafs match up against the Bruins?"
- "Compare Toronto and Montreal head-to-head"
- "What's the season series between NYR and NYI?"

#### `get_team_streak`
Get a team's current winning or losing streak.

**Parameters:**
- `teamAbbrev` (required): Team abbreviation

**Example queries:**
- "What's the Maple Leafs' current streak?"
- "Is Boston on a winning streak?"
- "Show me the Rangers' recent results"

#### `compare_seasons`
Compare statistics across multiple seasons.

**Parameters:**
- `seasons` (required): Array of seasons in format YYYYYYYY
- `teamAbbrev` (optional): Specific team to compare

**Example queries:**
- "Compare the Maple Leafs' performance over the last 3 seasons"
- "How has scoring changed from 2022 to 2024?"
- "Compare league-wide stats between 20232024 and 20242025"

## Common Team Abbreviations

| Team | Abbreviation |
|------|--------------|
| Anaheim Ducks | ANA |
| Arizona Coyotes | ARI |
| Boston Bruins | BOS |
| Buffalo Sabres | BUF |
| Calgary Flames | CGY |
| Carolina Hurricanes | CAR |
| Chicago Blackhawks | CHI |
| Colorado Avalanche | COL |
| Columbus Blue Jackets | CBJ |
| Dallas Stars | DAL |
| Detroit Red Wings | DET |
| Edmonton Oilers | EDM |
| Florida Panthers | FLA |
| Los Angeles Kings | LAK |
| Minnesota Wild | MIN |
| Montreal Canadiens | MTL |
| Nashville Predators | NSH |
| New Jersey Devils | NJD |
| New York Islanders | NYI |
| New York Rangers | NYR |
| Ottawa Senators | OTT |
| Philadelphia Flyers | PHI |
| Pittsburgh Penguins | PIT |
| San Jose Sharks | SJS |
| Seattle Kraken | SEA |
| St. Louis Blues | STL |
| Tampa Bay Lightning | TBL |
| Toronto Maple Leafs | TOR |
| Vancouver Canucks | VAN |
| Vegas Golden Knights | VGK |
| Washington Capitals | WSH |
| Winnipeg Jets | WPG |

## Natural Language Examples

Once configured with Claude Desktop, you can ask natural language questions like:

- "What NHL games are on tonight?"
- "Who's leading the league in goals?"
- "Show me the Atlantic division standings"
- "How are the Maple Leafs doing this season?"
- "What's the score of the Rangers game?"
- "Compare Toronto and Boston head-to-head"
- "Who are the top 5 goalies by save percentage?"
- "Is Edmonton on a winning streak?"
- "Show me the playoff bracket"
- "When does Montreal play next?"

## Data Source

This server uses the official NHL API endpoints:
- `api-web.nhle.com` - Primary data source for games, standings, and schedules
- `api.nhle.com/stats/rest` - Statistics and player data

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Development mode with watch
npm run dev
```

## License

MIT