cfbd

The CFBD MCP server provides access to College Football Data API v2 data through a Claude-enabled workflow. It exposes endpoints and prompts to fetch game results, team records, player stats, play-by-play data, and advanced metrics. You can issue natural language queries via Claude or use the provided endpoints/prompts to retrieve structured data such as games, plays, rankings, and win probabilities. Typical use cases include comparing teams, analyzing game outcomes, and generating insights from play-by-play data.

To use the server, run it locally with the UV package manager and point Claude Desktop to the server configuration. You can then query resources like get-games, get-plays, get-rankings, and get-pregame-win-probability through the connected MCP prompts or by invoking the corresponding endpoints documented in the schema. Ensure your API key is configured in the environment to authenticate with the CFBD API, and monitor rate limits as documented in the API limits section.

Prerequisites:

• Python 3.11 or higher
• UV package manager (uv)
• Git
• A College Football Data API key

Option A: Install via UV (recommended for Claude Desktop integration)

1. Clone the repository:

git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server

2. Create and activate a virtual environment (recommended):

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

3. Install the package in editable mode:

uv pip install -e .

4. Create an environment file with your API key (or set env var later):

CFB_API_KEY=your_api_key_here

5. Run the server:

uv run cfbd-mcp-server

Option B: Manual development setup (same steps, useful for contributing)

1. Clone the repository and navigate to it:

git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server

2. Create and activate a virtual environment:

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

3. Install dependencies:

uv pip install -e .

4. Add your API key to a .env file or environment:

CFB_API_KEY=your_api_key_here

5. Start the server:

uv run cfbd-mcp-server

Tips and notes:

• Ensure the CFB_API_KEY is valid and has access to the CFBD API. You can also export CFB_API_KEY in your shell or set it in Claude Desktop's environment configuration.
• The server uses UV to run and expects the module name cfbd-mcp-server as the entry point. If you rename the package, update the run command accordingly.
• Be mindful of API rate limits; leverage query efficiency and caching where possible.
• When integrating with Claude Desktop, follow the provided example claude_desktop_config.json snippet to connect the MCP server and ensure the environment paths (like PATH to Python) are correct for your system.
• For development, run tests with pytest as documented in the repo’s Development section.
• If you encounter key errors, ensure both the .env file and Claude Desktop config point to the same API key and that the key is valid on collegefootballdata.com.