cfbd-mcp-server
by: lenwood
An MCP server enabling CFBD API queries within Claude Desktop.
π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 within Claude Desktop.
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.
Sample Output
Q. What was the largest upset among FCS games during the 2014 season?
A. The biggest FCS upset from 2014 was Eastern Washington defeating Washington 52-59 on September 6th, 2014. Key points:
- Washington was an FBS team from the Pac-12 conference
- The game was played at Washington's home stadium (Husky Stadium)
- Eastern Washington's win probability was only 1.4% post-game
- The 59 points scored was the most ever by an FCS team against a Pac-12 opponent
- Washington had been favored by multiple scores going into the game
Other notable FCS upsets that season included North Dakota State defeating Iowa State 34-14, Bethune-Cookman defeating FIU 14-12, and Northern Iowa nearly upsetting Iowa (lost 31-23).
Eastern Washington over Washington stands out as the largest upset due to the division difference, caliber of opponent, scoring margin, historical significance, and the hostile away environment.
Prerequisites
- Python 3.11 or higher
- UV package manager (recommended): https://docs.astral.sh/uv/
- A College Football Data API key: https://collegefootballdata.com/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
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 at:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
-
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.
Upon restart, a small hammer icon will appear in the lower right corner of the textbox, indicating MCP tools are available.
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:
Windows:
rmdir /s /q build dist
del /s /q *.egg-info
macOS/Linux:
rm -rf build dist *.egg-info
- Install the revised package and dependencies:
uv pip install -e .
uv sync --dev --all-extras
- Run the server:
uv run cfbd-mcp-server
- Close and restart Claude Desktop.
Features
Resources
Access schema documentation for all endpoints:
schema://games
- Game information and scoresschema://records
- Team season recordsschema://games/teams
- Detailed team game dataschema://plays
- Play-by-play informationschema://drives
- Drive summaries and resultsschema://play/stats
- Individual play statisticsschema://rankings
- Team rankings across pollsschema://metrics/wp/pregame
- Pregame win probabilitiesschema://game/box/advanced
- Advanced box score statistics
Tools
Query endpoints directly:
get-games
- Retrieve game dataget-records
- Get team recordsget-games-teams
- Access team game statisticsget-plays
- Query play-by-play dataget-drives
- Analyze drive informationget-play-stats
- View play statisticsget-rankings
- Check team rankingsget-pregame-win-probability
- See win probabilitiesget-advanced-box-score
- Access detailed game statistics and analytics
Prompts
Pre-built analysis templates:
analyze-game
- Get detailed analysis of a specific gameanalyze-team
- Comprehensive single team analysisanalyze-trends
- Analyze trends over a seasoncompare-teams
- Compare performance of two teamsanalyze-rivalry
- Analyze historical rivalry matchups
API Limits
The College Football Data API is free with rate limits:
- Free tier: Limited requests per minute
- Patreon subscribers get higher rate limits: https://www.patreon.com/collegefootballdata
- 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 your changes
- Push to your fork
- Submit a pull request
Troubleshooting
Common Issues
-
API Key Errors
- Verify your API key is correctly set in both
.env
andclaude_desktop_config.json
- Check key validity at collegefootballdata.com
- Verify your API key is correctly set in both
-
Rate Limiting
- Space out requests
- Consider Patreon subscription for higher limits
- Implement caching
-
Connection Issues
- Verify internet connectivity
- Check API status at collegefootballdata.com
- Ensure proper error handling
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.
Acknowledgments
- College Football Data for providing the API
- Model Context Protocol for the MCP specification