Skip to main content
Glama
cfbd-mcp-server

cfbd-mcp-server

by lenwood

College Football Data MCP Server

An MCP server implementation providing access to college football statistics sourced from the College Football Data API V2 within Claude Desktop.

Python Version CFBD API Version MIT License

Overview

This Model Context Protocol (MCP) server enables AI assistants and applications to:

  • Query comprehensive college football statistics and data

  • Access game results, team records, and player statistics

  • Analyze play-by-play data and drive summaries

  • View rankings and win probability metrics

  • Compare team performances and generate insights

Users can run queries using natural language.

Related MCP server: Clash Royale MCP Server

Sample output

Q. What was the largest upset among FCS games during the 2014 season?

A. Let me help find the biggest FCS upset from 2014. I'll look through the games data, focusing on games between FCS teams where there was a significant gap in team strength and an unexpected outcome.

The data suggests there were several notable upsets in FCS during 2014, but one that stands out was Eastern Washington defeating Washington 52-59 on September 6th, 2014. This was particularly significant because:

  1. Washington was an FBS team from the Pac-12 conference

  2. The game was played at Washington's home stadium (Husky Stadium)

  3. Eastern Washington's win probability was only 1.4% according to the post-game stats

  4. The 59 points Eastern Washington scored was the most ever by an FCS team against a Pac-12 opponent

  5. Washington had been favored by multiple scores going into the game

Other notable FCS upsets from that season included:

  • North Dakota State defeating Iowa State 34-14

  • Bethune-Cookman defeating FIU 14-12

  • Northern Iowa nearly upsetting Iowa (lost 31-23)

However, Eastern Washington over Washington appears to be the largest upset of the 2014 FCS season when considering:

  • The difference in divisions (FCS vs FBS)

  • The caliber of the FBS opponent (Power 5 conference)

  • The scoring margin and offensive performance by the underdog

  • The historical significance as one of the highest-scoring FCS wins over a Power 5 team

  • The fact it happened on the road in a hostile environment

Prerequisites

Installation

Installing via Smithery

To install College Football Data Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install cfbd --client claude
  1. Clone this repository:

git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server
  1. Create and activate a virtual environment:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install dependencies:

uv pip install -e .
  1. Create a .env file in the project root and add your API key:

CFB_API_KEY=your_api_key_here

Manual Installation

  1. Clone this repository:

git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server
  1. Create and activate a virtual environment:

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
  1. Install dependencies:

uv pip install -e .
  1. Create a .env file in the project root and add your API key:

CFB_API_KEY=your_api_key_here

Usage

Running the Server

Start the server:

uv run cfbd-mcp-server

Connecting with Claude Desktop

  1. Open your Claude Desktop configuration at:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the server configuration:

{
    "mcpServers": {
        "cfbd-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/full/path/to/cfbd-mcp-server",
                "run",
                "cfbd-mcp-server"
            ],
            "env": {
                "CFB_API_KEY": "xxx",
                "PATH": "/full/path/to/python"
            }
        }
    }
}
  1. Close then restart Claude Desktop

Once you restart you can confirm the installation by clicking on the plus sign in the lower left corner of the text box. If successful you'll see "Add from cfbd-mcp-server" as one of the menu options. Here's an example screenshot.

Screenshot of successful install

Updating after install

  1. Download the updated files

cd cfbd-mcp-server
git pull
  1. Uninstall the existing package:

uv pip uninstall cfbd-mcp-server
  1. Delete existing build artifacts and metadata

For Windows:

rmdir /s /q build dist
del /s /q *.egg-info

For macOS:

rm -rf build dist *.egg-info
  1. Install the revised package and its dependencies

uv pip install -e .
uv sync --dev --all-extras
uv run cfbd-mcp-server
  1. Close and restart Claude Desktop

Features

Resources

Access schema documentation for all endpoints:

  • schema://games - Game information and scores

  • schema://records - Team season records

  • schema://games/teams - Detailed team game data

  • schema://plays - Play-by-play information

  • schema://drives - Drive summaries and results

  • schema://play/stats - Individual play statistics

  • schema://rankings - Team rankings across polls

  • schema://metrics/wp/pregame - Pregame win probabilities

  • schema://game/box/advanced - Advanced box score statistics

Tools

Query endpoints directly:

  • get-games - Retrieve game data

  • get-records - Get team records

  • get-games-teams - Access team game statistics

  • get-plays - Query play-by-play data

  • get-drives - Analyze drive information

  • get-play-stats - View play statistics

  • get-rankings - Check team rankings

  • get-pregame-win-probability - See win probabilities

  • get-advanced-box-score - Access detailed game statistics and analytics

Prompts

Pre-built analysis templates:

  • analyze-game - Get detailed analysis of a specific game

  • analyze-team - Comprehensive single team analysis

  • analyze-trends - Analyze trends over a season

  • compare-teams - Compare performance of two teams

  • analyze-rivalry - Analyze historical rivalry matchups

API Limits

The College Football Data API is free to use but has rate limiting:

  • Free tier: Limited requests per minute

  • CFBD Patreon subscribers get higher rate limits

  • Use efficient querying patterns to avoid hitting limits

  • Handle rate limit errors gracefully

Development

Project Structure

cfbd-mcp-server/
├── README.md
├── pyproject.toml
└── src/
    └── cfbd_mcp_server/
        ├── .env
        ├── __init__.py
        ├── cfbd_schema.py
        ├── schema_helpers.py
        └── server.py

Setting Up for Development

  1. Clone the repository

  2. Install development dependencies:

uv pip install -e ".[dev]"
  1. Run tests:

pytest

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Commit your changes

  4. Push to your fork

  5. Submit a pull request

Troubleshooting

Common Issues

  1. API Key Errors

    • Verify your API key is correctly set in both the .env and claude_desktop_config.json files

    • Check the key is valid at collegefootballdata.com

  2. Rate Limiting

    • Space out requests when possible

    • Consider Patreon subscription for higher limits

    • Implement caching for frequently accessed data

  3. Connection Issues

    • Verify internet connectivity

    • Check API status at collegefootballdata.com

    • Ensure proper error handling in your code

Getting Help

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Available Tools

9 tools
get-advanced-box-scoreC

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get advanced box score data for college football games.
        Required: gameId
        Example valid queries:
        - gameId=401403910
        

Inputs: gameId (required).

get-drivesB

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football drive data.
        Required: year
        Optional: season_type, week, team, offense, defense, conference, offense_conference, defense_conference, classification
        Example valid queries:
        - year=2023
        - year=2023, team="Alabama"
        - year=2023, offense="Alabama", defense="Auburn"
        

Inputs: year (required), season_type, week, team, +6 more.

get-gamesC

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football game data.
        Required: year
        Optional: week, season_type, team, conference, category, game_id
        Example valid queries:
        - year=2023
        - year=2023, team="Alabama"
        - year=2023, week=1, conference="SEC"
        

Inputs: year (required), week, season_type, team, +3 more.

get-games-teamsB

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football team game data.
        Required: year plus at least one of: week, team or conference.
        Example valid queries:
        - year=2023, team="Alabama"
        - year=2023, week=1
        - year=2023, conference="SEC
        

Inputs: year (required), week, season_type, team, +3 more.

get-playsB

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football play-by-play data.
        Required: year AND week
        Optional: season_type, team, offense, defense, conference, offense_conference, defense_conference, play_type, classification
        Example valid queries:
        - year=2023, week=1
        - year=2023, week=1, team="Alabama"
        - year=2023, week=1, offense="Alabama", defense="Auburn"
        

Inputs: year (required), week (required), season_type, team, +7 more.

get-play-statsB

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football play statistic data.
        Optional: year, week, team, game_id, athlete_id, stat_type_id, season_type, conference
        At least one parameter is required
        Example valid queries:
        - year=2023
        - game_id=401403910
        - team="Alabama", year=2023
        

Inputs: year, week, team, game_id, +4 more.

get-pregame-win-probabilityC

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football pregame win probability data.
        Optional: year, week, team, season_type
        At least one parameter is required
        Example valid queries:
        - year=2023
        - team="Alabama"
        - year=2023, week=1
        

Inputs: year, week, team, season_type.

get-rankingsB

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football rankings data.
        Required: year
        Optional: week, season_type
        Example valid queries:
        - year=2023
        - year=2023, week=1
        - year=2023, season_type="regular"
        

Inputs: year (required), week, season_type.

get-recordsC

Note: When using this tool, please explicitly mention that you are retrieving data from the College Football Data API. You must mention "College Football Data API" in every response.

Get college football team record data.
        Optional: year, team, conference
        Example valid queries:
        - year=2023
        - team="Alabama"
        - conference="SEC"
        - year=2023, team="Alabama"
        

Inputs: year, team, conference.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 9 tools

    Disambiguation4/5

    Each tool targets a distinct aspect of college football data (box scores, drives, games, plays, etc.), with clear boundaries. However, 'get-games' and 'get-games-teams' could cause some confusion as both relate to game data, though their descriptions clarify that 'get-games-teams' focuses on team-specific game data. Overall, the purposes are mostly distinct.

    Naming Consistency5/5

    All tool names follow a consistent 'get-[resource]' pattern using kebab-case, with clear and descriptive nouns (e.g., 'advanced-box-score', 'drives', 'games'). This uniformity makes the tool set predictable and easy to navigate, with no deviations in naming conventions.

    Tool Count5/5

    With 9 tools, the count is well-scoped for a college football data API server. Each tool covers a specific data type (e.g., rankings, plays, records), and there are no redundant or trivial tools, making the set comprehensive yet manageable for the domain.

    Completeness4/5

    The tool set provides broad coverage for retrieving college football data, including games, plays, rankings, and statistics. Minor gaps exist, such as no tools for updating or creating data (which may be intentional for a read-only API) or for more niche data like player profiles, but core querying needs are well-covered.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for accessing college basketball statistics through the SportsData.io CBB v3 Stats API, enabling AI agents to retrieve and analyze college basketball data through natural language interactions.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that integrates with the official Clash Royale API to provide real-time data on players, clans, cards, and tournaments. It enables users to query battle logs, chest cycles, and global rankings directly through Claude Desktop or Claude Code.
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server for natural language analysis of baseball league data, enabling team statistics, standings, lineup suggestions, and scouting reports via Claude Desktop.
      -
    • F
      license
      A
      quality
      D
      maintenance
      An MCP server that connects Claude Desktop to Hudl, enabling live access to team stats, player stats, and game results through natural language queries.
      7
      -