Flaim - Fantasy League AI Connector

Doc routing: see docs/INDEX.md.

Flaim connects your ESPN fantasy leagues to AI assistants like Claude, ChatGPT, and Gemini CLI. It's an MCP (Model Context Protocol) service that gives AI tools access to your live fantasy data.

How It Works

Create a Clerk account & sign in — This is where your ESPN credentials and league info are stored
Sync ESPN credentials — Install the Chrome extension to sync automatically, or enter them manually
Leagues auto-discovered — Extension finds all your leagues + past seasons and saves them
Pick a default — Select which league to use by default in AI conversations
Connect your AI — Add Flaim as a custom MCP connector in Claude, ChatGPT, or Gemini CLI using the MCP URL
Use MCP tools — Ask about your roster, matchups, standings, etc. directly in your AI

Bring your own LLM subscription. Flaim provides the data bridge.

Automation vs Manual (Quick Clarification)

Extension (automatic): Auto-pulls ESPN s2/swid and saves to supabase. Runs only when the user clicks Sync / Re-sync. It discovers leagues + past seasons and can set a default.
Site (manual): /leagues is independent. Users can add leagues by ID and manually trigger season discovery.

What Flaim Is

Flaim is an authentication and data service for fantasy sports AI integrations:

MCP Server: Exposes fantasy league data to Claude and ChatGPT via the Model Context Protocol
OAuth Provider: Handles secure authentication between AI clients and your ESPN data
Credential Manager: Securely stores and manages ESPN session cookies

Flaim is not a chatbot or AI product itself — it's the bridge that lets you use your preferred AI tool with your fantasy data.

Features

Chrome Extension (v1.5.0): Auto-capture ESPN credentials without manual cookie extraction
Auto-Discovery (v1.2.1+): Fan API-based discovery of leagues + past seasons, with granular status messaging and default selection
Claude + ChatGPT + Gemini CLI: Direct access via MCP protocol (OAuth 2.1)
Live ESPN Data: espn-client worker with real-time stats
Multi-League + Multi-Season Support: Store multiple seasons per league and discover past seasons

About

Flaim is a solo indie project — built with care, maintained for the long term. The focus is on reliability, security, and doing one thing well. No VC funding, no growth pressure, just a useful tool for fantasy sports fans who use AI.

Season Years

Season year defaults are deterministic and use America/New_York time:

Baseball (flb): Defaults to the previous year until Feb 1, then switches to the current year
Football (ffl): Defaults to the previous year until Jul 1, then switches to the current year

MCP Tools

The unified gateway (https://api.flaim.app/mcp) exposes these tools:

Tool	Description
`get_user_session`	User's leagues across all platforms with IDs
`get_ancient_history`	Historical leagues and seasons (2+ years old)
`get_league_info`	League settings and members
`get_roster`	Team roster with player stats
`get_matchups`	Current/upcoming matchups
`get_standings`	League standings
`get_free_agents`	Available free agents

All tools take explicit parameters: platform, sport, league_id, season_year.

Architecture

Chrome Extension → flaim.app → Auth Worker → Supabase
                      ↓
Claude/ChatGPT/Gemini CLI → Fantasy MCP Gateway → ESPN Client → ESPN API

Chrome Extension: Captures ESPN cookies, syncs to Flaim
Web App (Next.js): User dashboard, OAuth endpoints, league management
Auth Worker (Cloudflare): Token validation, rate limiting, credential storage
Fantasy MCP Gateway (Cloudflare): Unified MCP endpoint for all sports
ESPN Client (Cloudflare): ESPN API calls (internal, called by gateway)
Supabase: User data, OAuth tokens, ESPN credentials

For Contributors

Solo developer, hobby project. Keep it simple and stable.

Small changes — 1-2 hour tasks, one new concept at a time
Boring tech — Stick to the stack (Next.js, Vercel, Clerk, Cloudflare, Supabase)
Official docs first — Copy from examples before inventing patterns

Documentation

Document	Description
Architecture	System design, deployment, troubleshooting
Current Execution State	What is done, in progress, and next
Changelog	Release history
Web App	Next.js routes, components, environment
Workers	Cloudflare Workers, MCP tools, ESPN API
Manual OAuth Runbooks	Claude, ChatGPT, and Gemini verification checklists
Extension	Chrome extension build, Sync Host, CWS

Quick Start (Development)

git clone https://github.com/jdguggs10/flaim.git
cd flaim && npm install
cp web/.env.example web/.env.local  # add keys
npm run dev

Getting Help

This is a solo indie project with best-effort support. I'll do my best to respond, but it may take time.

Issues: GitHub Issues
Discussions: GitHub Discussions

License

MIT License - see LICENSE.

Flaim - Fantasy Sports AI Connector