ESPN MCP Server 🏈🏀⚾🏒⚽
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 endpointGET /mcp- Server-Sent Events (SSE) streamingGET /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