Commish MCP

An MCP (Model Context Protocol) server for fantasy sports league commissioners — giving AI assistants league-wide context and commissioner-oriented tools.

Commish MCP is not a thin wrapper around a single fantasy API. The domain is fantasy commissioner operations: league overviews, standings, matchup results, manager activity, transactions, recaps, and storylines. Provider-specific APIs (Yahoo first) sit underneath a provider abstraction.

Current state

🚧 Early development — initial scaffolding.

• MCP server boots over stdio and registers one example tool (get_league_overview)

• Provider-agnostic architecture with a Yahoo skeleton in place

• No live fantasy data yet — the Yahoo OAuth2 client and API integration are not implemented

Related MCP server: Omnicord - Discord server management MCP for AI agents

Planned providers

Planned capabilities

Commissioner-focused tools on the roadmap (none implemented yet):

• Weekly recaps and league storylines

• League health and manager activity

• Lineup auditing

• Transaction reports

• Playoff context and standings deep-dives

Architecture

Yahoo API
   ↓
YahooProvider            (src/providers/yahoo)
   ↓
Normalized domain models (src/domain)
   ↓
Commissioner services    (src/services)
   ↓
MCP tools                (src/tools)
   ↓
AI client

Key principles:

• Provider independence — tools operate on normalized domain models (src/domain), never raw provider payloads. Raw Yahoo types live in src/providers/yahoo/types.ts and must not leak upward.

• Commissioner-first — services (src/services) combine provider data into league-level views; tool handlers stay thin.

• Strong typing — provider payloads and domain objects are separate types; no any.

Getting started

Requires Node.js 22+ (.nvmrc provided).

npm install
npm run build
npm test
npm run typecheck

Scripts

Adding to an MCP client

Example Claude Desktop configuration:

{
  "mcpServers": {
    "commish-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/commish-mcp/dist/index.js"]
    }
  }
}

Configuration

Copy .env.example to .env (never committed) and fill in Yahoo credentials from an app registered at developer.yahoo.com/apps:

YAHOO_CLIENT_ID=
YAHOO_CLIENT_SECRET=
YAHOO_REDIRECT_URI=http://localhost:8787/callback

All variables are optional today: without them the server runs and tools explain what is missing. OAuth2 support (authorization-code flow, token refresh, secure local token storage) is the next milestone.

Project structure

src/
├── index.ts              # stdio entrypoint
├── server/server.ts      # server assembly + tool registration
├── tools/                # MCP tools (thin handlers)
│   ├── league/
│   └── types.ts          # ToolModule / ToolContext pattern
├── services/             # commissioner services (combine provider data)
├── providers/
│   ├── provider.ts       # FantasyProvider interface
│   └── yahoo/            # client, provider, raw payload types
├── domain/               # normalized league/team/matchup/transaction models
├── config/env.ts         # zod-validated environment
└── utils/
tests/                   # vitest unit + in-memory MCP integration tests

License

MIT