CFBD API MCP Server for College Football

Overview

The CFBD API MCP Server exposes College Football Data (CFBD) information—live scores, team stats, schedules, and game metadata—through a Model Context Protocol (MCP)-compatible service. It acts as a thin, low-latency layer between downstream apps or LLMs and the CFBD REST API: performing request shaping, caching, rate-limit handling, and providing standardized endpoints that are easy to call from chat models or client apps.

This server is useful when you want reliable, scalable access to college football data without embedding CFBD keys in client code or managing complex pagination/formatting. It is designed for developers building live scoreboards, analytics pipelines, chatbots, broadcast overlays, fantasy apps, or any system that needs fast access to current season schedules and box-score-level stats.

Features

• Lightweight MCP server that proxies CFBD API calls with MCP semantics
• Low-latency endpoints tuned for live-score and stats lookups
• Built-in caching (in-memory or Redis) to reduce CFBD quota usage
• Health, metrics, and basic rate-limiting for production readiness
• Simple JSON API compatible with MCP requester patterns
• Docker and local development support

Installation / Configuration

Prerequisites: Node.js 18+ and npm (or Docker).

Clone and install:

git clone https://github.com/lenwood/cfbd-mcp-server.git
cd cfbd-mcp-server
npm ci

Create an environment configuration (copy from example):

cp .env.example .env
# Edit .env to add your CFBD API key and adjust settings

Minimum required environment variables:

PORT=3000
CFBD_API_KEY=your_cfbd_api_key_here
CACHE_TTL_SECONDS=30
LOG_LEVEL=info
REDIS_URL=redis://localhost:6379  # optional

Start locally:

npm start
# or for development with auto-reload
npm run dev

Run with Docker:

docker build -t cfbd-mcp-server .
docker run -e CFBD_API_KEY=$CFBD_API_KEY -p 3000:3000 cfbd-mcp-server

You can also add the service to docker-compose and attach a Redis container for caching.

Available Resources

The server exposes HTTP endpoints that combine CFBD data with MCP-tool routing. Common endpoints include health checks, metrics, direct CFBD wrappers, and an MCP-compatible query endpoint.

Endpoint overview:

Use the /mcp endpoint to forward tool calls from an LLM or MCP-compliant client. The direct /cfbd/* endpoints are convenient for server-to-server calls or client widgets.

Use Cases

1. Live scoreboard widget (client-side)

   • Periodically call the server’s /cfbd/games/today to retrieve current game status, scores, and quarter/time. The server caches results to minimize CFBD API usage and returns JSON ready for display.

   Example:

   curl "http://localhost:3000/cfbd/games/today"
   

2. Chatbot integration via MCP

   • An LLM can request context through the MCP /mcp POST endpoint; the server resolves CFBD tool invocations (e.g., “get latest Alabama vs. LSU score”) and returns structured context that the model can use in responses.

   Example MCP request (simplified):

   {
     "id": "req-123",
     "tool_calls": [
       { "tool": "cfbd.getGame", "args": { "team": "Alabama", "opponent": "LSU" } }
     ]
   }
   

3. Analytics pipeline or daily ETL

   • Scheduled jobs pull season schedules and game stats using /cfbd/schedule/:year and /cfbd/game/:gameId/boxscore to normalize and store historical data for analytics or model training.

   Example:

   curl "http://localhost:3000/cfbd/schedule/2025"
   

Notes and Best Practices

• Use the included caching and optional Redis backing to avoid hitting CFBD API rate limits.
• Protect the MCP server behind authentication or network rules when exposing it to end-user clients.
• Tune CACHE_TTL and connection pooling for the traffic profile of your app.
• Consult the CFBD API docs for available query parameters and rate limits; the server forwards most standard query patterns but may normalize responses for MCP use.

Repository and source code: https://github.com/lenwood/cfbd-mcp-server

For MCP specification and best practices, refer to the Model Context Protocol documentation relevant to your LLM platform.