NHL MCP Server (Python)

A Model Context Protocol (MCP) server that provides access to NHL live data and statistics through natural language queries. This is an idiomatic Python implementation of the NHL MCP server.

Features

• Live Game Data: Get real-time scores, game status, and schedules

• Team Statistics: Access comprehensive team performance data

• Player Statistics: Query top players by various categories (points, goals, assists, etc.)

• Goalie Statistics: Specialized goalie metrics including save percentage and GAA

• Standings: Current NHL standings with filtering by division or conference

• Head-to-Head Comparisons: Compare teams and analyze matchup history

• Streak Analysis: Track team winning/losing streaks

• Season Comparisons: Compare statistics across multiple NHL seasons

• Playoff Data: Access playoff brackets and series information

Installation

From Source

1. Clone this repository

2. Install dependencies:

Using pip (once published)

Usage

Running the Server

The server communicates via stdio and is designed to be used with MCP clients:

Or if installed via pip:

Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

Or if using a virtual environment:

Available Tools

get_live_games

Get live NHL game scores and status for today or a specific date.

Parameters:

• date (optional): Date in YYYY-MM-DD format

Example:

get_game_details

Get detailed information about a specific game including play-by-play data.

Parameters:

• gameId (required): The NHL game ID

Example:

get_standings

Get current NHL standings with optional filtering.

Parameters:

• date (optional): Date in YYYY-MM-DD format

• division (optional): Atlantic, Metropolitan, Central, or Pacific

• conference (optional): Eastern or Western

Example:

get_team_stats

Get detailed statistics for a specific NHL team.

Parameters:

• teamAbbrev (required): Team abbreviation (e.g., TOR, NYR, BOS)

• season (optional): Season in format YYYYYYYY (e.g., 20242025)

Example:

get_player_stats

Get statistics for top NHL players.

Parameters:

• category (optional): points, goals, assists, plusMinus, shots, shootingPctg

• limit (optional): Number of players to return (default: 20)

• season (optional): Season in format YYYYYYYY

Example:

get_goalie_stats

Get statistics for NHL goalies.

Parameters:

• limit (optional): Number of goalies to return (default: 20)

• season (optional): Season in format YYYYYYYY

Example:

get_schedule

Get NHL schedule for upcoming games.

Parameters:

• date (optional): Date in YYYY-MM-DD format

• teamAbbrev (optional): Team abbreviation for specific team schedule

Example:

get_playoff_bracket

Get current playoff bracket information.

Parameters:

• season (optional): Season year (e.g., 2024)

Example:

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:

get_team_streak

Get current winning or losing streak for a team.

Parameters:

• teamAbbrev (required): Team abbreviation

Example:

compare_seasons

Compare statistics across multiple NHL seasons.

Parameters:

• seasons (required): Array of seasons to compare

• teamAbbrev (optional): Team abbreviation for team-specific comparison

Example:

Team Abbreviations

Common NHL team abbreviations:

• Atlantic: TOR (Toronto), BOS (Boston), MTL (Montreal), TBL (Tampa Bay), FLA (Florida), OTT (Ottawa), DET (Detroit), BUF (Buffalo)

• Metropolitan: NYR (Rangers), NYI (Islanders), CAR (Carolina), NJD (New Jersey), PHI (Philadelphia), PIT (Pittsburgh), WSH (Washington), CBJ (Columbus)

• Central: COL (Colorado), DAL (Dallas), MIN (Minnesota), WPG (Winnipeg), NSH (Nashville), STL (St. Louis), ARI (Arizona), CHI (Chicago)

• Pacific: VGK (Vegas), EDM (Edmonton), LAK (Los Angeles), SEA (Seattle), CGY (Calgary), VAN (Vancouver), SJS (San Jose), ANA (Anaheim)

API Data Sources

This server interfaces with the official NHL APIs:

• api-web.nhle.com - Primary data source for games, standings, and schedules

• api.nhle.com/stats/rest - Statistics and player data

Development

Requirements

• Python 3.10 or higher

• Dependencies listed in requirements.txt

Project Structure

Code Style

This implementation follows Python best practices:

• Type hints throughout using Python 3.10+ syntax

• Pydantic models for data validation

• Async/await for all I/O operations

• Snake_case naming conventions

• Comprehensive docstrings

Testing

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.