ESPN MCP Server 🏈🏀⚾🏒⚽

Version License TypeScript MCP SDK

A modern, production-ready Model Context Protocol (MCP) server that provides comprehensive access to ESPN's hidden sports APIs. Built with enhanced tool handlers, advanced parameter support, and complete coverage of all major sports leagues.

🚀 Features

Core Capabilities

20+ Specific ESPN Endpoints - Direct access to ESPN's hidden API endpoints
Advanced Parameter Support - Date filtering, week numbers, season types, team IDs
Multi-Transport Support - STDIO and HTTP streaming with MCP compliance
Comprehensive Sports Coverage - NFL, NBA, MLB, NHL, College Sports, Soccer
Smart Routing - Automatic endpoint selection based on sport/league combinations
Enhanced Tool Schemas - Rich parameter validation and documentation

Sports Coverage

🏈 NFL - National Football League (with week/season type filtering)
� College Football - Division I (with rankings and game summaries)
�🏀 NBA - National Basketball Association
🏀 WNBA - Women's National Basketball Association
🏀 College Basketball - Men's and Women's NCAA
⚾ MLB - Major League Baseball
⚾ College Baseball - NCAA Division I
� NHL - National Hockey League
⚽ MLS - Major League Soccer
⚽ Premier League - English Premier League
⚽ Champions League - UEFA Champions League

Enhanced Data Access

Live Scores with Filtering - Date-specific scores (YYYYMMDD format)
Team-Specific Data - Individual team information by abbreviation
Game Summaries - Detailed game breakdowns and statistics
College Football Rankings - Current AP and Coaches polls
Multi-League News - Sport-specific news aggregation
Historical Data - Season and career statistics

📋 Prerequisites

Node.js 18+ (ESM support required)
TypeScript 5.3+
npm or yarn package manager

🛠️ Installation

Quick Start

# Clone the repository git clone https://github.com/DynamicEndpoints/espn-mcp.git cd espn-mcp # Install dependencies npm install # Build the project npm run build # Start the server (STDIO mode) npm start # Or start HTTP server npm run start:modern:http

Docker Deployment

# Build Docker image npm run docker:build # Run with Docker Compose npm run docker:run # Stop services npm run docker:stop

Kubernetes Deployment

# Deploy to Kubernetes npm run k8s:deploy # Remove deployment npm run k8s:delete

🚀 Usage

STDIO Mode (Default)

Perfect for MCP client integration:

npm start:modern # or node build/modern-server.js

HTTP Mode

For web applications and REST API access:

npm run start:modern:http # or node build/modern-server.js --http --port 3000

Available Endpoints (HTTP Mode)

POST /mcp - Main MCP JSON-RPC endpoint
GET /mcp - Server-Sent Events (SSE) streaming
GET /health - Health check and capabilities

🔧 Available Tools

Enhanced Sports Tools

🏆 Live Scores with Advanced Filtering

get_live_scores({ sport: "football" | "basketball" | "baseball" | "hockey" | "soccer", league?: "nfl" | "college-football" | "nba" | "mens-college-basketball" | "womens-college-basketball" | "wnba" | "mlb" | "college-baseball" | "nhl" | "mls" | "premier-league" | "champions-league", dates?: string, // YYYYMMDD format (e.g., "20250826") week?: string, // NFL week number (e.g., "1", "17") seasontype?: "1" | "2" | "3" // 1=preseason, 2=regular, 3=postseason }) // Examples: // NFL Week 1 regular season: { sport: "football", league: "nfl", week: "1", seasontype: "2" } // NBA games on specific date: { sport: "basketball", league: "nba", dates: "20250826" } // College football scores: { sport: "football", league: "college-football" }

🏟️ Team Information

get_team_information({ sport: "football" | "basketball" | "baseball" | "hockey" | "soccer", league?: "nfl" | "college-football" | "nba" | "mens-college-basketball" | "womens-college-basketball" | "wnba" | "mlb" | "college-baseball" | "nhl" }) // Examples: // All NFL teams: { sport: "football", league: "nfl" } // College basketball teams: { sport: "basketball", league: "mens-college-basketball" }

🎯 Specific Team Details

get_specific_team({ sport: "football" | "basketball" | "baseball" | "hockey" | "soccer", league: "nfl" | "college-football" | "nba" | "mens-college-basketball" | "womens-college-basketball" | "wnba" | "mlb" | "nhl", team: string // Team abbreviation or identifier }) // Examples: // New England Patriots: { sport: "football", league: "nfl", team: "patriots" } // Georgia Tech: { sport: "football", league: "college-football", team: "gt" } // Los Angeles Lakers: { sport: "basketball", league: "nba", team: "lakers" }

🏆 College Football Rankings

get_college_football_rankings({}) // Returns current AP Poll, Coaches Poll, and CFP rankings

📊 Game Summary

get_game_summary({ sport: "football", // Currently football only league: "college-football", // Currently college-football only gameId: string // ESPN game identifier }) // Example: // 2017 Army vs Navy: { sport: "football", league: "college-football", gameId: "400934572" }

📈 League Standings

get_league_standings({ sport: "football" | "basketball" | "baseball" | "hockey" | "soccer", league?: string })

📰 Sports News with Multi-League Support

get_sports_news({ sport?: "football" | "basketball" | "baseball" | "hockey", limit?: number // Default: 10, Max: 50 }) // Examples: // All football news (NFL + College): { sport: "football" } // Basketball news (NBA + WNBA + College): { sport: "basketball", limit: 20 } // General sports news: {} (no parameters)

🔍 Athlete Search

search_athletes({ sport: "football" | "basketball" | "baseball" | "hockey" | "soccer", league?: string })

📊 Resources

Dynamic resources that update automatically:

Live Dashboard

URI: espn://live-dashboard
Description: Real-time sports scores across all major leagues
Updates: Every 30 seconds during live games

Breaking News

URI: espn://breaking-news
Description: Latest breaking news from the sports world
Updates: Every 5 minutes

Trending Athletes

URI: espn://trending-athletes
Description: Currently trending athletes and performances
Updates: Every 10 minutes

Playoff Picture

URI: espn://playoff-picture
Description: Current playoff standings and scenarios
Updates: Daily during playoff seasons

🤖 Interactive Prompts

AI-powered sports analysis and insights:

Game Performance Analysis

analyze_game_performance({ sport: string, // Required: The sport to analyze team_or_player: string, // Required: Team or player name game_context?: string // Optional: Specific game context })

Head-to-Head Comparison

compare_head_to_head({ sport: string, // Required: Sport for comparison entity1: string, // Required: First team/player entity2: string, // Required: Second team/player comparison_type?: string // Optional: "season", "career", "recent" })

Season Predictions

predict_season_outcomes({ sport: string, // Required: Sport to analyze league: string, // Required: Specific league prediction_scope?: string // Optional: "playoffs", "championship", "awards" })

🔧 Configuration

Environment Variables

# Optional: Custom ESPN API base URL ESPN_API_BASE_URL=https://site.api.espn.com/apis/site/v2/sports # Optional: Cache TTL in milliseconds (default: 300000 = 5 minutes) CACHE_TTL=300000 # Optional: HTTP server port (default: 3000) PORT=3000 # Optional: Enable debug logging DEBUG=true

MCP Client Configuration

For Claude Desktop or other MCP clients:

{ "mcpServers": { "espn": { "command": "node", "args": ["/path/to/espn-mcp/build/modern-server.js"], "env": { "NODE_ENV": "production" } } } }

🏗️ Architecture

Modern Design Patterns

Event-Driven Architecture - Real-time updates and notifications
Intelligent Caching - Multi-level caching with automatic invalidation
Resource Subscriptions - Live data streaming to connected clients
Error Recovery - Robust error handling and retry mechanisms
TypeScript First - Full type safety and IntelliSense support

Performance Features

Request Deduplication - Prevents redundant API calls
Batch Processing - Efficient handling of multiple requests
Connection Pooling - Optimized HTTP client configuration
Memory Management - Automatic cleanup and garbage collection

📚 Enhanced API Examples

Advanced Live Scores

// Get NFL Week 5 regular season scores const nflScores = await callTool("get_live_scores", { sport: "football", league: "nfl", week: "5", seasontype: "2" // Regular season }); // Get NBA games for a specific date const nbaScores = await callTool("get_live_scores", { sport: "basketball", league: "nba", dates: "20250826" }); // Get College Football scores const cfbScores = await callTool("get_live_scores", { sport: "football", league: "college-football" });

Team-Specific Data

// Get detailed info about the New England Patriots const patriotsInfo = await callTool("get_specific_team", { sport: "football", league: "nfl", team: "patriots" }); // Get Georgia Tech football team details const gtInfo = await callTool("get_specific_team", { sport: "football", league: "college-football", team: "gt" }); // Get Los Angeles Lakers information const lakersInfo = await callTool("get_specific_team", { sport: "basketball", league: "nba", team: "lakers" });

College Football Enhancements

// Get current college football rankings const rankings = await callTool("get_college_football_rankings", {}); // Get detailed game summary (2017 Army vs Navy example) const gameSummary = await callTool("get_game_summary", { sport: "football", league: "college-football", gameId: "400934572" });

Multi-League News

// Get comprehensive football news (NFL + College) const footballNews = await callTool("get_sports_news", { sport: "football", limit: 15 }); // Get basketball news from all leagues (NBA, WNBA, College) const basketballNews = await callTool("get_sports_news", { sport: "basketball" }); // Get general sports news const allNews = await callTool("get_sports_news", { limit: 20 });

Soccer Leagues

// Get MLS scores const mlsScores = await callTool("get_live_scores", { sport: "soccer", league: "mls" }); // Get Premier League scores const plScores = await callTool("get_live_scores", { sport: "soccer", league: "premier-league" }); // Get Champions League scores const clScores = await callTool("get_live_scores", { sport: "soccer", league: "champions-league" });

Resource Subscription

// Subscribe to live dashboard updates const resource = await readResource("espn://live-dashboard"); // Handle resource updates server.onResourceUpdate((uri, data) => { if (uri === "espn://live-dashboard") { console.log("Live scores updated:", data); } });

Interactive Prompts

// Analyze team performance const analysis = await getPrompt("analyze_game_performance", { sport: "football", team_or_player: "Kansas City Chiefs", game_context: "last 5 games" }); // Compare players head-to-head const comparison = await getPrompt("compare_head_to_head", { sport: "basketball", entity1: "LeBron James", entity2: "Michael Jordan", comparison_type: "career" });

🐳 Docker Support

Dockerfile

Multi-stage build optimized for production:

FROM node:18-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci --only=production FROM node:18-alpine WORKDIR /app COPY --from=builder /app/node_modules ./node_modules COPY build ./build EXPOSE 3000 CMD ["node", "build/modern-server.js", "--http"]

Docker Compose

version: '3.8' services: espn-mcp-server: build: . ports: - "3000:3000" environment: - NODE_ENV=production - PORT=3000 restart: unless-stopped

☸️ Kubernetes Support

Deployment Configuration

apiVersion: apps/v1 kind: Deployment metadata: name: espn-mcp-server spec: replicas: 3 selector: matchLabels: app: espn-mcp-server template: metadata: labels: app: espn-mcp-server spec: containers: - name: espn-mcp-server image: espn-mcp-server:latest ports: - containerPort: 3000 env: - name: NODE_ENV value: "production"

🔍 Monitoring & Health Checks

Health Endpoint

curl http://localhost:3000/health

Response:

{ "status": "healthy", "version": "2.0.0", "timestamp": "2025-08-24T10:30:00.000Z", "capabilities": { "resources": { "subscribe": true, "listChanged": true }, "prompts": { "listChanged": true }, "tools": { "listChanged": true }, "streaming": true, "sessionManagement": true } }

Logging

Structured logging with different levels:

Error: Critical failures and exceptions
Warn: Non-critical issues and degraded performance
Info: General operational messages
Debug: Detailed troubleshooting information

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone and setup git clone https://github.com/DynamicEndpoints/espn-mcp.git cd espn-mcp npm install # Development mode with auto-reload npm run dev:modern # Run tests npm test # Lint code npm run lint

Code Style

TypeScript with strict mode enabled
ESLint for code quality
Prettier for formatting
Conventional Commits for commit messages

🔒 Security

Input Validation - All inputs validated with Zod schemas
Rate Limiting - Built-in protection against abuse
CORS Configuration - Secure cross-origin resource sharing
Error Handling - No sensitive information leaked in errors

📈 Performance

Benchmarks

Response Time: < 100ms for cached data
Throughput: 1000+ requests/second
Memory Usage: < 100MB typical operation
Cache Hit Rate: > 95% for live data

Optimization Tips

Use resource subscriptions for real-time data
Cache frequently accessed data locally
Batch multiple requests when possible
Monitor memory usage in long-running processes

🐛 Troubleshooting

Common Issues

Connection Timeouts

# Increase timeout for slow networks export REQUEST_TIMEOUT=30000

Memory Issues

# Reduce cache TTL for memory-constrained environments export CACHE_TTL=60000

Port Conflicts

# Use different port npm run start:modern:http -- --port 3001

Debug Mode

# Enable verbose logging DEBUG=espn:* node build/modern-server.js

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

ESPN for providing comprehensive sports data APIs
Model Context Protocol team for the excellent SDK and specification
TypeScript and Node.js communities for robust tooling
Contributors who help improve this project

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Email: support@dynamicendpoints.com

Built with ❤️ by the DynamicEndpoints team