readme.mdβ’17.3 kB
# ESPN MCP Server ππβΎπβ½
[](https://github.com/DynamicEndpoints/espn-mcp)
[](LICENSE)
[](https://www.typescriptlang.org/)
[](https://github.com/modelcontextprotocol/typescript-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
```bash
# 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
```bash
# Build Docker image
npm run docker:build
# Run with Docker Compose
npm run docker:run
# Stop services
npm run docker:stop
```
### Kubernetes Deployment
```bash
# Deploy to Kubernetes
npm run k8s:deploy
# Remove deployment
npm run k8s:delete
```
## π Usage
### STDIO Mode (Default)
Perfect for MCP client integration:
```bash
npm start:modern
# or
node build/modern-server.js
```
### HTTP Mode
For web applications and REST API access:
```bash
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
```typescript
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
```typescript
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
```typescript
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
```typescript
get_college_football_rankings({})
// Returns current AP Poll, Coaches Poll, and CFP rankings
```
#### π Game Summary
```typescript
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
```typescript
get_league_standings({
sport: "football" | "basketball" | "baseball" | "hockey" | "soccer",
league?: string
})
```
#### π° Sports News with Multi-League Support
```typescript
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
```typescript
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
```typescript
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
```typescript
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
```typescript
predict_season_outcomes({
sport: string, // Required: Sport to analyze
league: string, // Required: Specific league
prediction_scope?: string // Optional: "playoffs", "championship", "awards"
})
```
## π§ Configuration
### Environment Variables
```bash
# 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:
```json
{
"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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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
```javascript
// 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:
```dockerfile
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
```yaml
version: '3.8'
services:
espn-mcp-server:
build: .
ports:
- "3000:3000"
environment:
- NODE_ENV=production
- PORT=3000
restart: unless-stopped
```
## βΈοΈ Kubernetes Support
### Deployment Configuration
```yaml
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
```bash
curl http://localhost:3000/health
```
Response:
```json
{
"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](CONTRIBUTING.md) for details.
### Development Setup
```bash
# 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
```bash
# Increase timeout for slow networks
export REQUEST_TIMEOUT=30000
```
#### Memory Issues
```bash
# Reduce cache TTL for memory-constrained environments
export CACHE_TTL=60000
```
#### Port Conflicts
```bash
# Use different port
npm run start:modern:http -- --port 3001
```
### Debug Mode
```bash
# Enable verbose logging
DEBUG=espn:* node build/modern-server.js
```
## π License
This project is licensed under the **MIT License** - see the [LICENSE](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](https://github.com/DynamicEndpoints/espn-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/DynamicEndpoints/espn-mcp/discussions)
- **Email**: support@dynamicendpoints.com
---
**Built with β€οΈ by the DynamicEndpoints team**