cfbd-mcp-server
The cfbd-mcp-server provides access to comprehensive college football statistics and data via the College Football Data API. With this server, you can:
Query game results, team records, and player statistics
Analyze play-by-play data and drive summaries
Access rankings, win probability metrics, and advanced box score statistics
Filter data by year, week, team, conference, season type, and other parameters
Compare team performances and generate insights using natural language queries
Utilize pre-built analysis templates for game, team, trend, comparison, and rivalry analysis
Access detailed schema documentation for various data endpoints
Mentions College Football Data's Patreon subscription option that provides higher rate limits for API access, enabling more frequent queries for comprehensive college football statistics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cfbd-mcp-server show me Alabama's 2023 season results"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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:
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% according to the post-game stats
The 59 points Eastern Washington 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 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
Python 3.11 or higher
UV package manager (recommended)
A College Football Data API key (get one here)
Installation
Installing via Smithery
To install College Football Data Server for Claude Desktop automatically via Smithery:
npx -y @smithery/cli install cfbd --client claudeClone this repository:
git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-serverCreate and activate a virtual environment:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activateInstall dependencies:
uv pip install -e .Create a
.envfile in the project root and add your API key:
CFB_API_KEY=your_api_key_hereManual Installation
Clone this repository:
git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-serverCreate and activate a virtual environment:
uv venv
source .venv/bin/activate # On Windows: .venv\Scripts\activateInstall dependencies:
uv pip install -e .Create a
.envfile in the project root and add your API key:
CFB_API_KEY=your_api_key_hereUsage
Running the Server
Start the server:
uv run cfbd-mcp-serverConnecting with Claude Desktop
Open your Claude Desktop configuration at:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%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
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.

Updating after install
Download the updated files
cd cfbd-mcp-server
git pullUninstall the existing package:
uv pip uninstall cfbd-mcp-serverDelete existing build artifacts and metadata
For Windows:
rmdir /s /q build dist
del /s /q *.egg-infoFor macOS:
rm -rf build dist *.egg-infoInstall the revised package and its dependencies
uv pip install -e .
uv sync --dev --all-extrasuv run cfbd-mcp-serverClose 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 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.pySetting Up for Development
Clone the repository
Install development dependencies:
uv pip install -e ".[dev]"Run tests:
pytestContributing
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 the
.envandclaude_desktop_config.jsonfilesCheck the key is valid at collegefootballdata.com
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 at collegefootballdata.com
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 - see the LICENSE file for details.
Acknowledgments
College Football Data for providing the API
Model Context Protocol for the MCP specification
Available Tools
9 toolsget-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
Scored across 9 tools
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.
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.
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.
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
Related MCP Connectors
MCP server giving Claude AI access to 22+ NYC public-record databases for real estate due diligence
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- FlicenseNot gradedqualityDmaintenanceAn 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.-
- FlicenseNot gradedqualityCmaintenanceMCP server for natural language analysis of baseball league data, enabling team statistics, standings, lineup suggestions, and scouting reports via Claude Desktop.-
- FlicenseAqualityDmaintenanceAn MCP server that connects Claude Desktop to Hudl, enabling live access to team stats, player stats, and game results through natural language queries.7-
Appeared in Searches
- Accessing Facebook Settings and Preferences
- A service for accessing music through Apple Music
- A tool for finding maps or creating visual representations
- Setting up productivity and collaboration tools like Google Sheets, Docs, Airtable, Slack, and more
- A server for discovering sports-related information