Fantasy-Football-AI-CoManager

JayMishra-source/Fantasy-Football-AI-CoManager

3.2

If you are the rightful owner of Fantasy-Football-AI-CoManager and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

This MCP server integrates with ESPN Fantasy Football to provide advanced analysis and recommendations for managing your fantasy team.

Tools
8
Resources
0
Prompts
0

Fantasy Football AI CoManager 🏈🤖

An intelligent ESPN Fantasy Football management system that combines automated GitHub Actions workflows with Claude Desktop integration through MCP (Model Context Protocol). The system analyzes your ESPN leagues and provides AI-driven recommendations for lineup optimization, waiver wire targets, and trade analysis.

🎯 What This Does

Transform your fantasy football management with AI that:

  • Analyzes your ESPN leagues - Fetches real-time data from ESPN Fantasy API
  • Optimizes lineups - Sets optimal lineups based on projections and matchups
  • Identifies waiver targets - Finds breakout players before your competition
  • Evaluates trades - Provides fair trade analysis with projected impact
  • Runs automatically - GitHub Actions or on-demand through Claude Desktop

🚀 Quick Start

Choose Your Path

Path 1: GitHub Actions Automation (Set It & Forget It)

Best for: Users who want automated daily/weekly analysis sent to Discord

Path 2: Claude Desktop + MCP (Interactive AI Assistant)

Best for: Users who want conversational AI help with fantasy decisions

Path 3: Local POC (Development & Testing)

Best for: Developers who want to test ESPN API integration

📚 Documentation

Core Documentation

  • - Easy setup guide for non-developers
  • - Visual flowchart of the automation workflow
  • - Integration with Claude Desktop
  • - Recent ESPN API data collection improvements
  • - Advanced AI system documentation

For Developers

  • - Instructions for Claude Code development
  • - AI prompting guidelines

🛠️ Installation

Prerequisites

  • Node.js 16+ and npm
  • ESPN Fantasy Football account
  • GitHub account (for Actions) OR Claude Desktop (for MCP)

Option 1: GitHub Actions Setup

  1. Fork this repository
  2. Get ESPN cookies (see Authentication section)
  3. Add GitHub Secrets: 
    ESPN_S2          # Your espn_s2 cookie
ESPN_SWID        # Your SWID cookie  
LEAGUE_1_ID      # Your league ID
LEAGUE_1_TEAM_ID # Your team ID
GEMINI_API_KEY   # Google Gemini API key (free tier)
DISCORD_WEBHOOK_URL # Discord channel webhook
  4. Enable GitHub Actions in your fork
  5. Automated runs:
    • Daily at 8 AM ET
    • Hourly during games (Sun/Mon/Thu)
    • Manual trigger anytime

Option 2: Claude Desktop + MCP Setup

  1. Clone repository:

    git clone https://github.com/yourusername/FantasyCoManager.git
cd FantasyCoManager/fantasy-engine/mcp-server

  2. Build MCP server:

    npm install
npm run build

  3. Configure Claude Desktop (~/.config/Claude/claude_desktop_config.json):

    {
  "mcpServers": {
    "fantasy-football": {
      "command": "node",
      "args": ["/path/to/fantasy-engine/mcp-server/dist/index.js"],
      "cwd": "/path/to/fantasy-engine/mcp-server"
    }
  }
}

  4. Restart Claude Desktop and ask:

    • "Help me with my fantasy team"
    • "Who should I start this week?"
    • "Find waiver wire targets"

Option 3: Local Development POC

# Clone and navigate
git clone https://github.com/yourusername/FantasyCoManager.git
cd FantasyCoManager/fantasy-engine

# Quick start (both frontend and backend)
./start-poc.sh

# Or manually:
cd server && npm install && npm run dev  # Backend on :3003
cd client && npm install && npm run dev  # Frontend on :5173

🔐 ESPN Authentication

Getting Your ESPN Cookies

  1. Login to ESPN Fantasy in Chrome/Firefox
  2. Open DevTools (F12) → Application → Cookies
  3. Find on fantasy.espn.com:
    • espn_s2 - Long authentication token
    • SWID - UUID in curly braces like {123-456-789}
  4. Copy these values for configuration

Finding Your League Info

From your ESPN Fantasy league URL:

https://fantasy.espn.com/football/league?leagueId=123456
                                              ^^^^^^ Your League ID

https://fantasy.espn.com/football/team?leagueId=123456&teamId=3
                                                         ^^^^^^ Your Team ID

💡 Usage Examples

With GitHub Actions

Once configured, the system automatically:

  • Thursday 6 PM: Pre-game optimization
  • Sunday 11 AM: Final lineup checks
  • Monday 8 AM: Waiver wire analysis
  • Tuesday 10 AM: Trade recommendations

Results sent to your Discord channel.

With Claude Desktop

Ask Claude naturally:

  • "Show me my current roster"
  • "Who should I start: Player A or Player B?"
  • "What's the best waiver pickup this week?"
  • "Is this trade fair: My RB1 for their WR1?"

With Local POC

Access http://localhost:5173 to:

  • View your roster with live ESPN data
  • Test ESPN API endpoints
  • See player projections and stats

🏗️ Architecture

System Components

┌─────────────────────────────────────────────────┐
│                   User Interfaces                │
├──────────┬────────────┬────────────┬────────────┤
│  GitHub  │   Claude   │    Web     │    CLI     │
│  Actions │  Desktop   │    POC     │   Tools    │
└──────────┴────────────┴────────────┴────────────┘
                           │
┌─────────────────────────────────────────────────┐
│              Core Services Layer                 │
├──────────────────────────────────────────────────┤
│  • ESPN API Integration (Authentication, Data)   │
│  • FantasyPros Rankings Integration              │
│  • AI Orchestration (Gemini, Claude, GPT)        │
│  • Data Processing & Slot Categorization         │
└─────────────────────────────────────────────────┘
                           │
┌─────────────────────────────────────────────────┐
│                 Data Sources                     │
├──────────────────────────────────────────────────┤
│  • ESPN Fantasy API (Rosters, Matchups, Stats)   │
│  • FantasyPros (Expert Rankings, Projections)    │
│  • Weather API (Game Conditions)                 │
│  • News Feeds (Injury Reports, Breaking News)    │
└─────────────────────────────────────────────────┘

Key Features by Component

GitHub Actions Automation (fantasy-engine/automation/)

  • Phase 4 Advanced Intelligence System
  • Scheduled and manual workflows
  • Discord webhook notifications
  • Multi-league support

MCP Server (fantasy-engine/mcp-server/)

  • 10+ MCP tools for ESPN data access
  • Lineup optimization algorithms
  • Trade and waiver analysis
  • Direct Claude Desktop integration

Web POC (fantasy-engine/client/ + fantasy-engine/server/)

  • React 19 + TypeScript frontend
  • Express + Puppeteer backend
  • ESPN authentication handling
  • API testing interface

Shared Library (fantasy-engine/shared/)

  • ESPN API client with 2025 season support
  • Roster slot categorization (26 position types)
  • Projection normalization (weekly vs season)
  • AI workflow orchestration

🔧 Recent Improvements

ESPN Data Collection Fixes (Completed)

✅ Fixed weekly vs season projection logic
✅ Enhanced FantasyPros player matching with position validation
✅ Standardized ESPN API to use 2025 season
✅ Improved slot categorization for all roster positions
✅ Added comprehensive logging for debugging

Repository Cleanup (Completed)

✅ Removed duplicate MCP server (saved 40% repository size)
✅ Cleaned up 18 outdated documentation files
✅ Streamlined to essential, current documentation

🐛 Troubleshooting

Common Issues

"ESPN authentication failed"

  • Cookies expire after ~30 days
  • Get fresh cookies from ESPN website
  • Update secrets/config with new values

"No roster data available"

  • Verify League ID and Team ID are correct
  • Check if league is private (requires auth)
  • Ensure cookies are from correct ESPN account

"Port already in use" (Local POC)

  • Another instance is running
  • Kill existing process or use different port

GitHub Actions not running

  • Check if Actions are enabled in fork
  • Verify all secrets are set correctly
  • Check workflow logs for specific errors

Debug Commands

# Test ESPN authentication
curl -H "Cookie: espn_s2=YOUR_COOKIE; SWID=YOUR_SWID" \
  "https://lm-api-reads.fantasy.espn.com/apis/v3/games/ffl/seasons/2025/segments/0/leagues/YOUR_LEAGUE_ID"

# Check MCP server
node fantasy-engine/mcp-server/dist/index.js

# View GitHub Actions logs
# Go to Actions tab → Select workflow → View logs

📊 Performance

  • ESPN API Response: < 500ms average
  • Lineup Optimization: < 2 seconds
  • Full Analysis: < 5 seconds
  • MCP Tool Execution: < 1 second each
  • GitHub Actions Runtime: ~2-3 minutes total

🔒 Security & Privacy

  • ESPN cookies stored as secrets (GitHub) or locally (MCP/POC)
  • No credentials sent to third parties
  • AI providers receive only anonymized fantasy data
  • All data processing happens in your environment

🤝 Contributing

Contributions welcome! Areas for improvement:

  • Additional MCP tools for Claude
  • Enhanced trade algorithms
  • More LLM provider support
  • Dynasty league features
  • Keeper league optimization

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

  • ESPN Fantasy API (unofficial)
  • FantasyPros for expert rankings
  • Anthropic for Claude and MCP
  • Google for Gemini API
  • The fantasy football community

Built with ❤️ for fantasy football managers who want an AI edge

Not affiliated with ESPN or Disney. Use responsibly and within ESPN's terms of service.