mcp_espn_ff: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is an MCP (Model Context Protocol) server that provides LLMs like Claude with tools to interact with the ESPN Fantasy Football API. The server wraps the espn-api Python library and exposes its functionality through MCP tools.

Running the Server

The server is designed to be run by MCP clients like Claude Desktop. To test locally:

uv run espn_fantasy_server.py

Architecture

Single-File MCP Server

The entire server implementation is in espn_fantasy_server.py. It uses the FastMCP framework to define MCP tools.

Core Components

1. ESPNFantasyFootballAPI Class (lines 29-72)

   • Manages ESPN league instances with caching
   • Handles per-session credential storage (ESPN_S2 and SWID cookies)
   • Uses cache keys that include authentication info to support both public and private leagues

2. Session Management

   • Uses a simple SESSION_ID = "default_session" approach
   • Credentials are stored in memory per-session in the api.credentials dict
   • League instances are cached with keys that include auth info: {league_id}_{year}_{espn_s2}_{swid}

3. Football Year Logic (lines 23-25)

   • Defaults to current calendar year
   • If before July, uses previous year (since NFL season spans calendar years)

MCP Tools

The server exposes 8 tools (all async functions decorated with @mcp.tool()):

• authenticate() - Store ESPN credentials for accessing private leagues
• get_league_info() - Basic league information
• get_team_roster() - Player roster for a specific team
• get_team_info() - Team statistics and transaction info
• get_player_stats() - Stats for a specific player by name
• get_league_standings() - Current standings sorted by wins/points
• get_matchup_info() - Weekly matchup details
• logout() - Clear stored credentials

Error Handling

All tools:

• Use try/except blocks with logging to stderr via log_error()
• Check for 401 errors or "Private" in exceptions to detect private league access issues
• Return user-friendly string messages (not JSON) since MCP converts them