ESPN MCP Server 🏈🏀⚾🏒⚽

License

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: [email protected]

Built with ❤️ by the DynamicEndpoints team