franchise-mcp-server

An MCP (Model Context Protocol) server that lets LLMs read and edit Madden NFL franchise saves and EA SPORTS College Football dynasty saves (CFB 27+). It wraps bep713/madden-franchise — the community-standard parser behind tools like Franchise Editor — and exposes its full capability as 14 well-guarded tools.

Supported games (inherited from the library): Madden 19–27, College Football 27+. Both franchise saves and FTC (franchise-common) game-data files open.

┌────────────┐     MCP (stdio)     ┌─────────────────────┐        ┌──────────────────┐
│ LLM client │ ◄─────────────────► │ franchise-mcp-server │ ◄────► │ madden-franchise │ ◄── CAREER-* / DYNASTY-* files
└────────────┘                     └─────────────────────┘        └──────────────────┘

Layout

franchise-mcp-server/
├── src/                 TypeScript source
│   ├── index.ts         server + tool registrations
│   ├── session.ts       open-file sessions, table resolution, field loading
│   ├── serialize.ts     field value ⇄ JSON conversion, validation, pagination
│   ├── types.ts         structural types for the library
│   └── constants.ts
├── dist/                built JS (entry: dist/index.js)
├── tests/smoke-test.mjs end-to-end test (drives the server over stdio)
└── skills/franchise-editor/          ← docs for LLM agents
    ├── SKILL.md                       main skill (workflow + safety rules)
    └── references/
        ├── domain-model.md            file anatomy, references, free-lists
        ├── workflows.md               step-by-step recipes
        ├── cfb-notes.md               CFB 27 dynasty specifics
        └── library-api.md             building apps on the library directly

Related MCP server: StatsPlus MCP Server

Setup

Requires Node.js >= 22.19.0.

This server depends on madden-franchise via file:../madden-franchise — clone it as a sibling directory (the repo version includes CFB 27 support that is ahead of the npm release):

# 1. Clone both repos side by side
git clone https://github.com/bep713/madden-franchise.git
git clone https://github.com/<you>/franchise-mcp-server.git

# 2. Build the library
cd madden-franchise && npm install && npm run build

# 3. Build the server
cd ../franchise-mcp-server && npm install && npm run build

# 4. Smoke test against bundled CFB 27 test data (uses a copy!)
cp ../madden-franchise/tests/data/DYNASTY-27COMPRESS /tmp/DYNASTY-TEST
node tests/smoke-test.mjs /tmp/DYNASTY-TEST

Register with Claude Code (project .mcp.json)

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

Register with Claude Desktop (claude_desktop_config.json)

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

Give the agent the skills/franchise-editor/ folder (Claude Code discovers it from .claude/skills/; other agents can be pointed at SKILL.md directly).

Tool catalog

File lifecycle

Discovery

Reading

Writing

References & row lifecycle

Design notes

• Validation-first writes. The underlying library bit-packs values and will silently wrap out-of-range ints and corrupt free-lists if misused; this server rejects out-of-range/oversized/invalid-enum writes and empty-record writes with errors that state the valid values.

• Stable identity. Tools push agents toward table_unique_id (stable across files and game years) over file-specific tableIds and ambiguous names.

• Context-efficient. Everything is paginated and field-selectable; responses over ~25k chars truncate with explicit truncated_by_size + next_offset metadata.

• Edit-safe partial reads. Field lists load incrementally; pending edits are flushed to the table buffer before any re-read, so partial reads never lose unsaved changes.

• Sessions. Multiple files can be open at once (e.g. copy data between a Madden franchise and a CFB dynasty, or between a save and its backup).

Known table uniqueIds

Everything else: discover per-file with franchise_list_tables (name collisions are common — eight tables named Team exist in CFB 27; pick by record count).

License

MIT (the wrapped madden-franchise library is MIT by matthewpanetta/bep713).