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
- Clone this repository
- Install dependencies:
cd nhl-mcp-python
pip install -e .
Using pip (once published)
pip install nhl-mcp-server
Usage
Running the Server
The server communicates via stdio and is designed to be used with MCP clients:
python -m nhl_mcp.server
Or if installed via pip:
nhl-mcp-server
Configuration
Add to your MCP client configuration (e.g., Claude Desktop):
{
"mcpServers": {
"nhl": {
"command": "python",
"args": ["-m", "nhl_mcp.server"]
}
}
}
Or if using a virtual environment:
{
"mcpServers": {
"nhl": {
"command": "/path/to/venv/bin/python",
"args": ["-m", "nhl_mcp.server"]
}
}
}
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 today's NHL scores
Show me games on 2024-03-15
get_game_details
Get detailed information about a specific game including play-by-play data.
Parameters:
gameId(required): The NHL game ID
Example:
Get details for game 2024020123
get_standings
Get current NHL standings with optional filtering.
Parameters:
date(optional): Date in YYYY-MM-DD formatdivision(optional): Atlantic, Metropolitan, Central, or Pacificconference(optional): Eastern or Western
Example:
Show me the Atlantic division standings
Get Eastern conference standings
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 Toronto Maple Leafs stats
Show me Boston Bruins statistics
get_player_stats
Get statistics for top NHL players.
Parameters:
category(optional): points, goals, assists, plusMinus, shots, shootingPctglimit(optional): Number of players to return (default: 20)season(optional): Season in format YYYYYYYY
Example:
Show me top goal scorers
Get top 10 players by points
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:
Show me top goalies
Get top 15 goalies by save percentage
get_schedule
Get NHL schedule for upcoming games.
Parameters:
date(optional): Date in YYYY-MM-DD formatteamAbbrev(optional): Team abbreviation for specific team schedule
Example:
Show me the Maple Leafs schedule
Get NHL schedule for next week
get_playoff_bracket
Get current playoff bracket information.
Parameters:
season(optional): Season year (e.g., 2024)
Example:
Show me the current playoff bracket
Get 2024 playoff bracket
compare_teams
Compare head-to-head statistics between two teams.
Parameters:
team1(required): First team abbreviationteam2(required): Second team abbreviationseason(optional): Season in format YYYYYYYY
Example:
Compare Toronto and Montreal
Show me Bruins vs Rangers head to head
get_team_streak
Get current winning or losing streak for a team.
Parameters:
teamAbbrev(required): Team abbreviation
Example:
What's the Maple Leafs current streak?
Show me Boston's win/loss streak
compare_seasons
Compare statistics across multiple NHL seasons.
Parameters:
seasons(required): Array of seasons to compareteamAbbrev(optional): Team abbreviation for team-specific comparison
Example:
Compare the 2023-24 and 2024-25 seasons for Toronto
Compare league stats between 20232024 and 20242025
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 schedulesapi.nhle.com/stats/rest- Statistics and player data
Development
Requirements
- Python 3.10 or higher
- Dependencies listed in
requirements.txt
Project Structure
nhl-mcp-python/
├── src/
│ └── nhl_mcp/
│ ├── __init__.py
│ ├── __main__.py
│ ├── server.py # Main MCP server implementation
│ └── nhl_api.py # NHL API client with type models
├── pyproject.toml
├── requirements.txt
└── README.md
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
# Install development dependencies
pip install -e ".[dev]"
# Run tests (if you add them)
pytest
License
MIT
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.