College Football MCP (cfb-mcp)

A Python-based Model Context Protocol (MCP) server that provides real-time college football game information, betting odds, and historical performance data for teams and players.

Features

• Live Game Scores & Odds: Get real-time scores and betting odds for NCAA college football games
• Player Statistics: Retrieve last 5 games' stats for any player
• Team Performance: Get recent game results and team information
• Next Game Odds: Find upcoming games and their betting lines

Quick Start

Prerequisites

• Python 3.11+
• Docker (optional, for containerized deployment)
• API Keys:
  • The Odds API - for live scores and betting odds
  • CollegeFootballData API - for team and player statistics

Installation

1. Clone the repository:

git clone https://github.com/gedin-eth/cfb-mcp.git
cd cfb-mcp

2. Create 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

Running the Server

uvicorn src.server:app --host 0.0.0.0 --port 8000

Docker Deployment

Build the Docker image:

docker build -t cfb-mcp .

Run the container:

docker run -p 8000:8000 --env-file .env cfb-mcp

For VPS deployment, pull and run:

docker pull <your-registry>/cfb-mcp:latest
docker run -d -p 8000:8000 --env-file .env --name cfb-mcp cfb-mcp

API Endpoints

The MCP server exposes the following functions via both MCP protocol (/mcp/*) and REST API (/api/*) endpoints:

1. get_game_odds_and_score

Get live game scores and betting odds for a specific matchup.

POST /mcp/get_game_odds_and_score or GET /api/get_game_odds_and_score

Request:

{
  "team1": "Alabama",
  "team2": "Auburn"  // optional
}

Response:

{
  "home_team": "Alabama",
  "away_team": "Auburn",
  "start_time": "2025-11-25T19:00:00Z",
  "status": "completed",
  "score": {
    "home": 28,
    "away": 14
  },
  "odds": {
    "spread": {...},
    "moneyline": {...},
    "over_under": {...}
  }
}

2. get_recent_player_stats

Get player's last 5 games statistics.

POST /mcp/get_recent_player_stats or GET /api/get_recent_player_stats

Request:

{
  "player_name": "Jalen Milroe",
  "team": "Alabama"  // optional, for disambiguation
}

3. get_team_recent_results

Get team's last 5 game results.

POST /mcp/get_team_recent_results or GET /api/get_team_recent_results

Request:

{
  "team": "Alabama"
}

4. get_team_info

Get team's current season overview including record and rankings.

POST /mcp/get_team_info or GET /api/get_team_info

Request:

{
  "team": "Alabama"
}

5. get_next_game_odds

Get next scheduled game and betting odds for a team.

POST /mcp/get_next_game_odds or GET /api/get_next_game_odds

Request:

{
  "team": "Alabama"
}

Architecture

Phase 1: MCP Server (Completed ✅)

• FastAPI-based REST API server
• 5 core functions for college football data
• Integration with The Odds API and CollegeFootballData API

Phase 2: Full Web Application (In Progress)

• Agent Service: FastAPI chat service with LLM integration
• Web UI: Single-page chat interface (mobile-friendly)
• Caddy: Reverse proxy with automatic HTTPS
• Docker Compose: Multi-container orchestration

Development

This project follows the Model Context Protocol standard for AI agent integration.

Project Structure

cfb-mcp/
├── src/
│   ├── server.py          # FastAPI MCP server
│   ├── odds_api.py         # The Odds API client
│   └── cfbd_api.py         # CollegeFootballData API client
├── agent_service/          # Agent service (Phase 2)
├── web_ui/                # Web UI (Phase 2)
├── Dockerfile              # MCP server container
├── docker-compose.yml      # Multi-container setup (Phase 2)
├── Caddyfile              # Reverse proxy config (Phase 2)
└── requirements.txt       # Python dependencies

Environment Variables

Create a .env file in the project root with the following variables:

# 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

Getting API Keys

1. The Odds API: Sign up at the-odds-api.com
2. CollegeFootballData API: Get a free key at collegefootballdata.com
3. OpenAI API: Get your key from platform.openai.com

Architecture Overview

System Components

┌─────────────┐
│   Web UI    │ (Static HTML/JS)
│  (nginx)    │
└──────┬──────┘
       │
       │ HTTPS
       │
┌──────▼──────┐
│    Caddy    │ (Reverse Proxy)
│  (HTTPS)    │
└──────┬──────┘
       │
   ┌───┴───┐
   │       │
┌──▼───┐ ┌─▼────┐
│ Web  │ │Agent │
│  UI  │ │Service│
└──────┘ └───┬──┘
             │
        ┌────▼────┐
        │   MCP   │
        │ Server  │
        └────┬────┘
             │
    ┌────────┴────────┐
    │                 │
┌───▼───┐      ┌───────▼──────┐
│ Odds  │      │  CFBD API    │
│  API  │      │              │
└───────┘      └──────────────┘

Component Details

1. MCP Server (src/): FastAPI server exposing 5 core functions for college football data
2. Agent Service (agent_service/): FastAPI service that orchestrates LLM + MCP calls
3. Web UI (web_ui/): Single-page chat interface (mobile-friendly)
4. Caddy: Reverse proxy providing HTTPS and routing

Deployment

Quick Start with Docker Compose

1. Set up environment variables:

   cp .env.example .env
   # Edit .env and add your API keys
   

2. Update Caddyfile: Edit Caddyfile and replace cfb.yourdomain.com with your actual domain.

3. Deploy:

   docker compose up -d --build
   

4. Access:

   • Web UI: https://cfb.yourdomain.com
   • API: https://cfb.yourdomain.com/api/*

Domain Setup for Caddy

1. Point your domain to your VPS IP address (A record)

2. Ensure ports are open:

   • Port 80 (HTTP)
   • Port 443 (HTTPS)

3. Caddy will automatically:

   • Obtain SSL certificate from Let's Encrypt
   • Renew certificates automatically
   • Handle HTTPS redirects

Individual Service Deployment

MCP Server Only

docker build -t cfb-mcp .
docker run -p 8000:8000 --env-file .env cfb-mcp

Agent Service Only

cd agent_service
docker build -t cfb-agent .
docker run -p 8000:8000 --env-file ../.env cfb-agent

Troubleshooting

Common Issues

1. "Missing Bearer token" error:

   • Ensure APP_TOKEN is set in .env
   • Check that the token is being sent in the Authorization header

2. "ODDS_API_KEY is not configured":

   • Verify .env file exists and contains ODDS_API_KEY
   • Check that the MCP server container has access to the .env file

3. Caddy certificate issues:

   • Ensure domain DNS points to your server
   • Check that ports 80 and 443 are open
   • Verify Caddyfile domain matches your actual domain

4. Agent service can't reach MCP server:

   • Check MCP_SERVER_URL environment variable
   • Verify both services are on the same Docker network
   • Check service names in docker-compose.yml

5. OpenAI API errors:

   • Verify OPENAI_API_KEY is set correctly
   • Check API key has sufficient credits
   • Review OpenAI API rate limits

Logs

View logs for all services:

docker compose logs -f

View logs for specific service:

docker compose logs -f agent
docker compose logs -f mcp-server
docker compose logs -f caddy

Development

Running Locally (without Docker)

1. MCP Server:

   cd /path/to/cfb-mcp
   source venv/bin/activate
   uvicorn src.server:app --host 0.0.0.0 --port 8000
   

2. Agent Service:

   cd agent_service
   python -m venv venv
   source venv/bin/activate
   pip install -r requirements.txt
   uvicorn main:app --host 0.0.0.0 --port 8001
   

3. Web UI:

   • Serve with any static file server, or use nginx locally
   • Update API_BASE in index.html to point to agent service

License

MIT