NHL MCP Server

# NHL MCP Server A comprehensive Model Context Protocol (MCP) server for the NHL API, built with FastMCP. This server provides access to all documented NHL API endpoints through MCP tools, enabling AI assistants to access live NHL data. ## 🏒 Features This MCP server provides access to **40+ NHL API endpoints** including: ### Player Information - Player game logs (current and historical seasons) - Player detailed information and career statistics - Player spotlight and featured players - Player landing pages and biographical data ### Statistics - Current and historical skater stats leaders - Current and historical goalie stats leaders - Customizable statistical categories and limits - Season and career totals ### Team Information - Team standings (current and historical by date) - Team statistics and performance metrics - Team rosters with player details - Team schedules and upcoming games - Club statistics and team comparisons ### Game Information - Daily scores and live scoreboards - Game play-by-play data with detailed events - Game boxscores and statistical summaries - Game stories and match summaries - Game landing pages ### League Information - League schedules and season calendars - TV schedules and broadcast information - Streaming availability ("where to watch") - Network television schedules ### Playoff Information - Playoff overviews and tournament brackets - Playoff schedules and series information - Postseason statistics and records ### Additional Features - Season information and draft data - Meta information and API utilities - Team code references and format helpers - Comprehensive error handling ## 🚀 Installation 1. Clone or download this repository 2. Install the required dependencies: ```bash pip install -r requirements.txt ``` **Dependencies:** - `fastmcp>=2.8.0` - FastMCP framework for MCP server creation - `requests>=2.31.0` - HTTP library for API calls - `typing-extensions` - Enhanced type hints support ## 📖 Usage ### Running the Server Start the MCP server: ```bash python nhl_mcp_server.py ``` The server will start and listen for MCP connections. ### MCP Client Configuration Add this server to your MCP client configuration (e.g., Claude Desktop): ```json { "mcpServers": { "nhl-api": { "command": "python", "args": ["/path/to/nhl_mcp_server.py"] } } } ``` ### Testing the Server Run the test scripts to verify functionality: ```bash # Test the underlying NHL API client python test_client.py # Test the MCP server backend python test_mcp_server.py # Run a comprehensive demo python demo.py ``` ## 🛠️ Available Tools The server exposes the following MCP tools: ### Player Tools - `get_player_info(player_id)` - Get detailed player information - `get_player_game_log(player_id, season, game_type)` - Get player game logs - `get_player_spotlight()` - Get featured players ### Team Tools - `get_standings_now()` - Get current NHL standings - `get_club_stats_now(team)` - Get team statistics - `get_team_roster(team)` - Get team roster - `get_team_schedule(team)` - Get team schedule ### Game Tools - `get_daily_scores_now()` - Get today's scores - `get_play_by_play(game_id)` - Get game play-by-play - `get_game_boxscore(game_id)` - Get game boxscore ### Statistics Tools - `get_current_skater_stats_leaders()` - Get skater stat leaders - `get_current_goalie_stats_leaders()` - Get goalie stat leaders ### Schedule Tools - `get_schedule_now()` - Get current schedule - `get_tv_schedule_now()` - Get TV schedule ### Utility Tools - `get_team_codes()` - Get list of NHL team codes - `get_season_format_help()` - Get format help for seasons and parameters ## 📋 Parameter Formats ### Team Codes Use standard NHL team abbreviations: - `TOR` (Toronto Maple Leafs), `MTL` (Montreal Canadiens) - `NYR` (New York Rangers), `BOS` (Boston Bruins) - `EDM` (Edmonton Oilers), `CGY` (Calgary Flames) - And all other NHL teams ### Season Format Seasons use 8-digit format: `YYYYYYYY` - `20232024` for 2023-24 season - `20222023` for 2022-23 season ### Game Types - `2` - Regular season games - `3` - Playoff games ### Date Format Use ISO date format: `YYYY-MM-DD` - `2024-01-15` for January 15, 2024 ## 💡 Example Queries Once connected to an MCP client, you can ask: - *"What are the current NHL standings?"* - *"Show me Connor McDavid's stats this season"* - *"What games are on today?"* - *"Get the Toronto Maple Leafs roster"* - *"Who are the current goal scoring leaders?"* - *"Show me yesterday's game scores"* - *"Get the playoff bracket"* ## 🏗️ Architecture The project consists of: 1. **`nhl_api_client.py`** - Core NHL API client with 40+ endpoint functions 2. **`nhl_mcp_server.py`** - FastMCP server that exposes API functions as MCP tools 3. **`test_client.py`** - Test script for the NHL API client 4. **`test_mcp_server.py`** - Test script for the MCP server backend 5. **`demo.py`** - Comprehensive demonstration of server capabilities 6. **`requirements.txt`** - Python dependencies 7. **`mcp_config_example.json`** - Example MCP client configuration ## ✅ Testing & Validation The server has been thoroughly tested with: - **Live NHL Data**: All endpoints tested with current NHL season data - **Error Handling**: Robust error handling for API failures and invalid parameters - **Response Validation**: Proper handling of different response types (dict, list, etc.) - **MCP Compliance**: Full compatibility with MCP protocol standards **Test Results:** - ✅ 40+ NHL API endpoints working correctly - ✅ Live data retrieval (standings, scores, player stats) - ✅ MCP tool registration and exposure - ✅ Error handling and validation - ✅ Documentation and examples ## 🔧 Error Handling The server includes comprehensive error handling: - **HTTP Errors**: Network timeouts, connection failures, API unavailability - **JSON Parsing**: Malformed responses and unexpected data structures - **Parameter Validation**: Invalid team codes, player IDs, and date formats - **Rate Limiting**: Graceful handling of API rate limits All errors are returned as descriptive messages to help with debugging. ## 🤝 Contributing Feel free to contribute by: - Adding new NHL API endpoints as they become available - Improving error handling and validation - Adding more comprehensive tests - Enhancing documentation and examples - Reporting bugs or suggesting improvements ## 📄 License This project is open source. The NHL API is provided by the National Hockey League and is subject to their terms of service. ## 🖼️ Screenshots ### NHL MCP Server in Action  *Screenshot showing the NHL MCP Server providing live NHL data including current standings, player information, game scores, and statistics. The server successfully integrates with MCP clients to bring comprehensive hockey data to AI assistants.* --- **🏒 Ready to bring live NHL data to your AI assistant!**