Collegiate Gridiron Football Data Access Layer

This Model Context Protocol (MCP) server provides access to football statistics curated from the College Football Data API V2, designed for utilization within Claude Desktop.

Overview

This context protocol server facilitates AI agents and client applications to:

• Retrieve extensive college football numerical datasets and statistics
• Access final scores, team seasonal results, and player performance figures
• Scrutinize sequential play reports and summarizing drive summaries
• Examine official poll rankings and pre-game probability estimations
• Conduct comparative team performance analysis and derive actionable intelligence

Interrogation of the underlying data is achieved through conversational, natural language queries.

Illustrative Example

Q. Which contest represented the most substantial underdog victory amongst all contests involving an FCS competitor in the 2014 schedule?

A. I will now ascertain the maximal upset involving an FCS participant from the 2014 campaign. This involves scanning game logs, concentrating on matchups between FCS squads where initial assessments predicted significant disparity in capability, leading to an unexpected final tally.

The records indicate numerous significant upsets within the FCS domain in 2014, yet a standout result involves Eastern Washington's triumph over Washington, tallying 59-52 on September 6th, 2014. The magnitude of this result is amplified by several factors:

1. Washington belonged to the FBS subdivision and the Pac-12 conference.
2. The fixture was hosted at Washington's venue (Husky Stadium).
3. Statistical models placed Eastern Washington's pre-game win expectation at a mere 1.4%.
4. The 59 points achieved by Eastern Washington represents a record high for an FCS team against any Pac-12 counterpart.
5. Washington entered the contest favored by margins exceeding one score.

Further notable FCS upsets from that year include:

• North Dakota State winning 34-14 against Iowa State
• Bethune-Cookman edging FIU 14-12
• Northern Iowa narrowly losing 31-23 to Iowa

However, the Eastern Washington defeat of Washington remains the preeminent upset of the 2014 FCS season when evaluating:

• The subdivision gap (FCS versus FBS)
• The standing of the FBS opposition (Power 5 affiliation)
• The final point differential and offensive output from the conquering underdog
• Its historical importance as one of the highest-scoring road wins for an FCS team over a Power 5 team
• The context of achieving this result in an adversarial road environment

Necessary Components

• Python interpreter version 3.11 or newer
• The UV package manager (recommended for installation)
• An active College Football Data API authorization credential (obtain here)

Setup Procedures

Automated Installation via Smithery

To deploy the College Football Data Server for Claude Desktop using Smithery:

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

1. Obtain a local copy of the repository: bash git clone https://github.com/yourusername/cfbd-mcp-server cd cfbd-mcp-server

2. Provision and activate an isolated Python environment: bash uv venv source .venv/bin/activate # For Windows: .venv\Scripts\activate

3. Install project prerequisites: bash uv pip install -e .

4. Establish a .env configuration file in the root directory containing your credential: bash CFB_API_KEY=your_api_key_here

Manual Installation Steps

1. Obtain a local copy of the repository: bash git clone https://github.com/yourusername/cfbd-mcp-server cd cfbd-mcp-server

2. Provision and activate an isolated Python environment: bash uv venv source .venv/bin/activate # For Windows: .venv\Scripts\activate

3. Install project prerequisites: bash uv pip install -e .

4. Establish a .env configuration file in the root directory containing your credential: bash CFB_API_KEY=your_api_key_here

Operation

Launching the Server Process

Initiate the server execution: bash uv run cfbd-mcp-server

Integration with Claude Desktop

1. Navigate to the configuration file for Claude Desktop:
2. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

3. Windows: %APPDATA%\Claude\claude_desktop_config.json

4. Augment the server definitions:

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

1. Terminate and subsequently relaunch Claude Desktop.

Upon a successful initialization, interacting with the input text box's addition symbol (+) will reveal "Add from cfbd-mcp-server" as an available data source option. Refer to the accompanying visual guide for confirmation.

Post-Installation Revision

1. Retrieve updated files:

cd cfbd-mcp-server git pull

1. Deactivate the currently installed package instance:

uv pip uninstall cfbd-mcp-server

1. Erase residual build artifacts and catalog entries

For Windows OS: bash rmdir /s /q build dist del /s /q *.egg-info

For macOS: bash rm -rf build dist *.egg-info

1. Install the revised package alongside its prerequisites bash uv pip install -e . uv sync --dev --all-extras

uv run cfbd-mcp-server

1. Reinitiate Claude Desktop

Capabilities

Data Schemas

Consult the documentation for the structure of accessible data endpoints:

• schema://games - Information pertaining to contest outcomes and scores
• schema://records - Aggregated season performance metrics for squads
• schema://games/teams - Detailed team statistics aggregated per game event
• schema://plays - Granular sequences of actions within a contest
• schema://drives - Summaries detailing possession sequences and results
• schema://play/stats - Statistical decomposition for individual actions
• schema://rankings - Official poll standings for participating organizations
• schema://metrics/wp/pregame - Win probability assessments calculated prior to kickoff
• schema://game/box/advanced - In-depth analytical metrics derived from box scores

Query Functions

Direct access points for data retrieval:

• get-games - Fetch contest records
• get-records - Retrieve team historical performance summaries
• get-games-teams - Access team-specific statistical data sets
• get-plays - Query detailed play-by-play sequences
• get-drives - Examine possession sequences
• get-play-stats - Obtain statistics tied to specific plays
• get-rankings - Check current team standings in various polls
• get-pregame-win-probability - View calculated pre-match win expectations
• get-advanced-box-score - Access comprehensive post-game analytical statistics

Predefined Analysis Templates

Ready-to-use scripts for common analytical tasks:

• analyze-game - Generate a thorough breakdown of a single contest
• analyze-team - Conduct an exhaustive review of one team's status
• analyze-trends - Uncover patterns across an entire season's worth of data
• compare-teams - Perform a side-by-side performance evaluation of two squads
• analyze-rivalry - Examine the historical head-to-head results between rivals

API Constraint Management

The College Football Data API operates under usage limitations:

• Standard tier: Capped number of operations permitted per minute
• Patrons of the CFBD Patreon receive elevated access caps
• Users should employ efficient data fetching methodologies to circumvent imposed limits
• Implementation must include robust mechanisms for handling rate-limit error responses

Project Engineering

Directory Layout

cfbd-mcp-server/ ├── README.md ├── pyproject.toml └── src/ └── cfbd_mcp_server/ ├── .env ├── init.py ├── cfbd_schema.py ├── schema_helpers.py └── server.py

Initializing for Development Work

1. Clone the repository structure

2. Install development tooling dependencies: bash uv pip install -e ".[dev]"

3. Execute unit and integration tests: bash pytest

Collaboration Guidelines

1. Create a fork of the primary repository
2. Establish a dedicated feature branch for your modifications
3. Commit your alterations securely
4. Push the branch to your forked repository
5. Submit a formal Pull Request for review

Problem Resolution

Recurring Difficulties

1. Authorization Credential Issues
2. Verify the API key is correctly configured in both the .env file and the claude_desktop_config.json file

3. Confirm the key's validity via the collegefootballdata.com portal

4. Rate Limiting Encountered

5. Introduce deliberate delays between sequential API calls where feasible
6. Consider upgrading to a paid Patreon subscription for increased throughput

7. Integrate data caching solutions for frequently requested static information

8. Network Communication Failure

9. Confirm active, stable network connectivity
10. Monitor the API provider's status page for reported outages at collegefootballdata.com
11. Ensure the server code incorporates proper exception handling for connection failures

Seeking Assistance

• File a new issue report on the GitHub platform
• Consult the official API specifications
• Engage with the community on the College Football Data Discord server

Licensing

This software is distributed under the terms of the MIT License. Refer to the LICENSE file for complete particulars.

Acknowledgements

• Appreciation to College Football Data for furnishing the underlying data source
• Recognition of the Model Context Protocol specification framework WIKIPEDIA: XMLHttpRequest (XHR) represents a JavaScript programming interface, encapsulated within an object, facilitating the submission of HTTP requests from a web browser to a designated web server. These functions empower browser-resident applications to dispatch queries to the server subsequent to the initial page rendering, and subsequently receive back the requisite information. XMLHttpRequest forms a core element of the Ajax programming paradigm. Before Ajax gained prominence, server interaction predominantly relied upon clicking hyperlinks or submitting standard forms, actions which typically necessitated a full page refresh.

== Genesis == The foundational concept underpinning XMLHttpRequest was first formulated in 2000 by the engineering team responsible for Microsoft Outlook development. This concept was subsequently embedded within the Internet Explorer 5 browser release (1999). Critically, the initial syntax did not employ the unified 'XMLHttpRequest' identifier. Instead, developers utilized the constructor calls ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). Since the advent of Internet Explorer 7 (released in 2006), virtually all modern browsers have provided native support for the XMLHttpRequest identifier. The XMLHttpRequest identifier has since solidified its position as the universal standard across all major browser engines, including Mozilla's Gecko rendering core (adopted in 2002), Apple's Safari 1.2 (2004), and Opera 8.0 (2005).

=== Standardization Efforts === The World Wide Web Consortium (W3C) formally published a preliminary specification (Working Draft) for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C released the Level 2 specification draft. The Level 2 revisions introduced crucial functionalities such as monitoring the progress of asynchronous operations, enabling cross-site data retrieval, and facilitating the handling of raw byte streams. By the conclusion of 2011, the features defined in Level 2 were integrated back into the primary specification document. In late 2012, stewardship of the standard transitioned to the WHATWG, which now maintains an active, evolving document utilizing Web IDL notation.

== Operational Use == Generally, executing a data transmission using XMLHttpRequest requires adherence to a sequential series of programming steps.

1. Construct an XMLHttpRequest instance by invoking its designated constructor:
2. Invoke the "open" method to define the request method (GET/POST, etc.), specify the target Uniform Resource Identifier (URI), and designate whether the operation should be synchronous or asynchronous:
3. For asynchronous requests, attach an event handler function designed to execute when the request's operational state transitions:
4. Commencing the transaction via the "send" method, optionally transmitting payload data:
5. Processing state changes within the assigned event listener callback. Upon reception of server data, this content is typically accessible via the "responseText" attribute by default. When the object completes its processing cycle, its state transitions to 4, indicating the "complete" status. Beyond these fundamental operations, XMLHttpRequest affords extensive configuration options governing transmission protocols and response parsing mechanisms. Custom header fields can be appended to the outgoing transmission to dictate server behavior, and data can be uploaded to the server as an argument to the "send" call. The server response can be automatically deserialized from JSON structure into native JavaScript objects, or alternatively, processed incrementally as data segments arrive, obviating the need to await total reception. Furthermore, the outgoing request can be halted prematurely or configured with a timeout to enforce failure if completion is not achieved within a set timeframe.

== Inter-Domain Requests ==

During the nascent phases of the World Wide Web's evolution, restrictions were encountered that made it feasible to brea