README.md•7.59 kB
# 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