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.

• 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

• 🏈 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

• 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

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

# 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

# Build Docker image
npm run docker:build

# Run with Docker Compose
npm run docker:run

# Stop services
npm run docker:stop

# Deploy to Kubernetes
npm run k8s:deploy

# Remove deployment
npm run k8s:delete

Perfect for MCP client integration:

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

For web applications and REST API access:

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

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

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" }

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" }

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" }

get_college_football_rankings({})

// Returns current AP Poll, Coaches Poll, and CFP rankings

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" }

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

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)

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

Dynamic resources that update automatically:

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

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

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

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

AI-powered sports analysis and insights:

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
})

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"
})

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

# 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

For Claude Desktop or other MCP clients:

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

• 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

• 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

// 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"
});

// 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"
});

// 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"
});

// 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
});

// 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"
});

// 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);
  }
});

// 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"
});

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"]

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

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"

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
  }
}

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

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

# 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

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

• 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

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

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

# Increase timeout for slow networks
export REQUEST_TIMEOUT=30000

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

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

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

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

• 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

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

Built with ❤️ by the DynamicEndpoints team