College Football

You run a Python MCP server that provides real-time college football information, including live scores, betting odds, and historical stats for teams and players. It’s designed for easy integration with MCP clients, letting you fetch game results, odds, and player/team data on demand.

How to use

You interact with the MCP server through a client that supports MCP endpoints. Start the server locally, then query the available functions to retrieve live scores, upcoming game odds, and recent statistics. Typical use cases include checking the latest game odds for a specific matchup, retrieving the last five games for a player, or obtaining a team’s recent results.

Key capabilities you can leverage: fetch live game scores and odds for a matchup, retrieve a player’s last five games, obtain a team’s recent five-game results, view a team’s current season overview, and get odds for the next scheduled game for a team.

How to install

Prerequisites you need before installing: Python 3.11 or newer, and Docker (optional for containerized deployment). You will also require API keys for The Odds API and CollegeFootballData.

# 1) Clone the MCP server repository
git clone https://github.com/gedin-eth/cfb-mcp.git
cd cfb-mcp

# 2) Create and activate a virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# 3) Install dependencies
pip install -r requirements.txt

# 4) Set up environment variables
cp .env.example .env
# Edit .env and add your API keys

# 5) Run the MCP server directly (local development)
uvicorn src.server:app --host 0.0.0.0 --port 8000

If you prefer containerized deployment, you can build and run the Docker image. Use the same environment file to supply keys and settings.

# 6) Build and run with Docker
docker build -t cfb-mcp .
docker run -p 8000:8000 --env-file .env cfb-mcp

Configuration and environment variables

Create a .env file in the project root and define your API keys and configuration values. The server reads these variables at startup.

# MCP Server API Keys
ODDS_API_KEY=your_odds_api_key
CFB_API_KEY=your_cfbd_api_key

# Agent Service Configuration
APP_TOKEN=choose-a-long-random-string-here
OPENAI_API_KEY=your_openai_api_key_here

# Optional: MCP Server URL (defaults to http://localhost:8000)
# MCP_SERVER_URL=http://localhost:8000

What you can run now (endpoints and tools)

This MCP server exposes a set of endpoints for retrieving real-time data and historical information. You can call these endpoints to obtain current game odds and scores, player statistics, team results, and upcoming game odds.

Troubleshooting

Common issues and fixes you might encounter include missing Bearer token errors, missing API keys, certificate problems with SSL, and connectivity between services. Ensure your environment variables are correctly set, the MCP server is running, and network access between containers (if you’re using Docker) is properly configured.

If you need to inspect runtime details, view the logs of the MCP server process to diagnose startup or runtime failures.

Notes

The server is Python-based and relies on FastAPI for its REST API. It integrates with The Odds API for live odds and The CollegeFootballData API for team and player statistics.

Appendix: API endpoints you can use with the MCP client

The server provides a fixed set of functions that your MCP client can call to obtain data. See the endpoint list below for the available functions.

Available tools

get_game_odds_and_score

Fetch live game scores and betting odds for a specified matchup. Returns home/away teams, start time, status, score, and odds data.

get_recent_player_stats

Retrieve the last five games statistics for a given player, optionally scoped to a specific team.

get_team_recent_results

Return the last five game results for a specified team, including scores and outcomes.

get_team_info

Provide a current-season overview for a team, including overall record and rankings.

get_next_game_odds

Get the next scheduled game for a team along with betting odds.