home / mcp / cfbd mcp server

CFBD MCP Server

Provides access to College Football Data API v2 statistics for queries on games, teams, plays, and rankings.

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "lenwood-cfbd-mcp-server": {
      "url": "https://mcp.cfbd.example.com/mcp",
      "headers": {
        "PATH": "/usr/bin:/bin",
        "CFB_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

This MCP server provides access to College Football Data API statistics for use in AI assistants and apps. You can query game results, team records, player stats, and play-by-play data, then analyze trends, rankings, and win probabilities through natural language queries. Set up once, then connect your MCP client to run questions and receive structured data-backed insights.

How to use

You interact with the server through an MCP client by connecting to this local service. Start the server, then use your client to send questions like: Which team has the best offensive efficiency this season? What is the latest win probability for a given matchup? How did a specific drive unfold in a game? The client will fetch data from the server’s endpoints and return organized results, summaries, or analyses.

How to install

Prerequisites: you need Python 3.11 or higher and the UV package manager (recommended). You also need a College Football Data API key to access the data.

# Optional quick start via Smithery (if you use the Smithery flow):
npx -y @smithery/cli install cfbd --client claude
```

```
# Manual install flow
# 1. Clone the MCP server repo
git clone https://github.com/lenwood/cfbd-mcp-server
cd cfbd-mcp-server

# 2. Create and activate a Python virtual environment
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# 3. Install dependencies
uv pip install -e .

# 4. Create an environment file with your API key
#   You will reference this key when starting the server
CFB_API_KEY=your_api_key_here
```

```
# Start the server
uv run cfbd-mcp-server
```

```
# Optional: quick start via the Claude Desktop config (example structure)
# This snippet shows how Claude Desktop should reference the local server

Configuration and usage notes

The server relies on an API key for the College Football Data API. Place the key in a file named .env at the project root with the variable CFB_API_KEY. You will also configure the client (Claude Desktop in this example) to connect to the server using the runtime command shown above.

Troubleshooting and tips

If you encounter API key errors, verify that your key is valid and present as CFB_API_KEY in your environment. If you hit rate limits, space out requests or consider a higher tier. Ensure you have internet connectivity and that the API service is reachable.

Additional notes

Once the server is running, you can connect Claude Desktop and use the Add from cfbd-mcp-server option to integrate the MCP data flow into your workflow.

Available tools

get-games

Retrieve game data for specified criteria such as date range or team filters.

get-records

Obtain team season records and standings.

get-games-teams

Access detailed statistics for teams within specific games.

get-plays

Query play-by-play data for games or drives.

get-drives

Analyze drive summaries and results.

get-play-stats

View statistics for individual plays.

get-rankings

Check team rankings across polls and systems.

get-pregame-win-probability

See win probabilities before games begin.

get-advanced-box-score

Access advanced box score statistics and analytics.

analyze-game

Generate a detailed analysis for a specific game.

analyze-team

Provide comprehensive analysis for a single team.

analyze-trends

Identify trends over a season.

compare-teams

Compare performances between two teams.

analyze-rivalry

Examine historical rivalry matchups.