College Football Data MCP Server

Overview

• 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

Sample output

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

• North Dakota State defeating Iowa State 34-14

• Bethune-Cookman defeating FIU 14-12

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

• 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

• Python 3.11 or higher

• [UV package manager](https://docs.astral.sh/uv/) (recommended)

• A College Football Data API key ([get one here](https://collegefootballdata.com/key))

Installation

Installing via Smithery

1. Clone this repository:

1. Create and activate a virtual environment:

1. Install dependencies:

1. Create a `.env` file in the project root and add your API key:

Manual Installation

1. Clone this repository:

1. Create and activate a virtual environment:

1. Install dependencies:

1. Create a `.env` file in the project root and add your API key:

Usage

Running the 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:

1. Close then restart Claude Desktop

Updating after install

1. Download the updated files

1. Uninstall the existing package:

1. Delete existing build artifacts and metadata

1. Install the revised package and its dependencies

1. Close and restart Claude Desktop

Features

Resources

• `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

• `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

• `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

• Free tier: Limited requests per minute

• [CFBD Patreon subscribers](https://www.patreon.com/collegefootballdata) get higher rate limits

• Use efficient querying patterns to avoid hitting limits

• Handle rate limit errors gracefully

Development

Project Structure

Setting Up for Development

1. Clone the repository

2. Install development dependencies:

1. Run tests:

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

• Open an issue on GitHub

• Review the [API documentation](https://api.collegefootballdata.com/api/docs/?url=/api-docs.json)

• Check the [College Football Data Discord](https://discord.gg/cfbdata)

License

Acknowledgments

• [College Football Data](https://collegefootballdata.com/) for providing the API

• [Model Context Protocol](https://modelcontextprotocol.io) for the MCP specification