📌Overview

Purpose: This framework serves as an MCP server to enable AI assistants and applications to query and analyze college football statistics effectively.

Overview: The College Football Data MCP Server provides comprehensive access to a variety of college football data, allowing users to retrieve game results, team records, player statistics, and more. It supports natural language queries for user-friendly interactions with the data.

Key Features:

Comprehensive Data Access: Retrieve detailed statistics including game scores, team records, and player performance metrics to inform analyses and decisions.
Natural Language Queries: Users can input questions in plain language, making it easier to interact with the data without requiring technical knowledge.

College Football Data MCP Server

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

Overview

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

Query comprehensive college football statistics
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.

Prerequisites

Python 3.11 or higher
UV package manager (recommended)
A College Football Data API key

Installation

Installing via Smithery

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

npx -y @smithery/cli install cfbd --client claude

Clone this repository:

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

Create and activate a virtual environment:

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

Install dependencies:
```
uv pip install -e .
```
Create a .env file in the project root and add your API key:
```
CFB_API_KEY=your_api_key_here
```

Manual Installation

Clone this repository:

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

Create and activate a virtual environment:

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

Install dependencies:
```
uv pip install -e .
```
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

Open your Claude Desktop configuration:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

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"
            }
        }
    }
}

Close then restart Claude Desktop.

Updating after install

Download the updated files:
```
cd cfbd-mcp-server
git pull
```
Uninstall the existing package:
```
uv pip uninstall cfbd-mcp-server
```

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

Install the revised package and its dependencies:

uv pip install -e .
uv sync --dev --all-extras

Start the server again:
```
uv run cfbd-mcp-server
```
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
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 game analysis
analyze-team - Comprehensive team analysis
analyze-trends - Analyze seasonal trends
compare-teams - Compare two teams' performances
analyze-rivalry - Analyze historical rivalry matchups

API Limits

The College Football Data API has rate limiting:

Free tier: Limited requests per minute
Higher limits available for CFBD Patreon subscribers
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

Clone the repository.
Install development dependencies:
```
uv pip install -e ".[dev]"
```
Run tests:
```
pytest
```

Contributing

Fork the repository.
Create a feature branch.
Commit changes.
Push to your fork.
Submit a pull request.

Troubleshooting

Common Issues

API Key Errors
- Verify your API key is correctly set in both the .env and claude_desktop_config.json files.
Rate Limiting
- Space out requests when possible.
- Consider Patreon subscription for higher limits.
- Implement caching for frequently accessed data.
Connection Issues
- Verify internet connectivity.
- Check API status on the College Football Data website.
- Ensure proper error handling in your code.

Getting Help

Open an issue on GitHub.
Review the API documentation.
Check the College Football Data Discord.

License

This project is licensed under the MIT License.