College Football Data MCP Server

College Football Data MCP 服务

一种 MCP 服务实现，可在 Claude Desktop 中访问来自 College Football Data API V2 的大学橄榄球统计数据。

概述

此 Model Context Protocol（MCP）服务支持 AI 助手和应用：

• 查询全面的大学橄榄球统计数据
• 访问比赛结果、球队战绩和球员统计数据
• 分析逐档比赛数据和推进摘要
• 查看排名和获胜概率指标
• 比较球队表现并生成见解

用户可以使用自然语言进行查询。

输出示例

问：2014 赛季 FCS 比赛中最大的冷门是什么？

答：我来帮你找出 2014 年 FCS 中最大的冷门。我会查看比赛数据，重点关注 FCS 球队之间实力差距显著且结果出人意料的比赛。

数据表明，2014 年 FCS 出现过几场值得关注的冷门，其中最突出的一场是东华盛顿大学于 2014 年 9 月 6 日以 59-52 击败华盛顿大学。这场比赛尤为引人注目，原因如下：

1. 华盛顿大学是来自 Pac-12 联盟的 FBS 球队
2. 比赛在华盛顿大学的主场球场（Husky Stadium）举行
3. 根据赛后统计，东华盛顿大学的获胜概率仅为 1.4%
4. 东华盛顿大学拿下的 59 分，是 FCS 球队对阵 Pac-12 对手时的最高得分
5. 赛前华盛顿大学被认为至少领先多个达阵

该赛季其他值得关注的 FCS 冷门包括：

• 北达科他州立大学以 34-14 击败爱荷华州立大学
• 贝瑟恩-库克曼大学以 14-12 击败 FIU
• 北爱荷华大学险些爆冷击败爱荷华大学（以 23-31 告负）

不过，综合以下因素，东华盛顿大学击败华盛顿大学似乎是 2014 年 FCS 赛季最大的冷门：

• 分区级别差异（FCS 对阵 FBS）
• FBS 对手的实力（Power 5 联盟）
• 得分差距以及弱势方的进攻表现
• 其历史意义：这是 FCS 球队击败 Power 5 球队时得分最高的比赛之一
• 比赛是在客场、充满敌意的环境中进行的

前提条件

• Python 3.11 或更高版本
• UV 包管理器（推荐）
• College Football Data API 密钥（在此获取）

安装

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 College Football Data 服务：

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

1. 克隆此仓库：

git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server

2. 创建并激活虚拟环境：

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 安装依赖项：

uv pip install -e .

4. 在项目根目录中创建 .env 文件并添加你的 API 密钥：

CFB_API_KEY=your_api_key_here

手动安装

1. 克隆此仓库：

git clone https://github.com/yourusername/cfbd-mcp-server
cd cfbd-mcp-server

2. 创建并激活虚拟环境：

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

3. 安装依赖项：

uv pip install -e .

4. 在项目根目录中创建 .env 文件并添加你的 API 密钥：

CFB_API_KEY=your_api_key_here

使用方法

运行服务

启动服务：

uv run cfbd-mcp-server

连接 Claude Desktop

1. 打开 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

2. 添加服务配置：

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

3. 关闭并重启 Claude Desktop

重启后，点击文本框左下角的加号，即可确认是否安装成功。如果安装成功，你会在菜单选项中看到“Add from cfbd-mcp-server”。以下是示例截图。

安装后更新

1. 下载更新后的文件

cd cfbd-mcp-server
git pull

2. 卸载现有软件包：

uv pip uninstall cfbd-mcp-server

3. 删除现有的构建产物和元数据

Windows：

rmdir /s /q build dist
del /s /q *.egg-info

macOS：

rm -rf build dist *.egg-info

4. 安装修订后的软件包及其依赖项

uv pip install -e .
uv sync --dev --all-extras

uv run cfbd-mcp-server

6. 关闭并重启 Claude Desktop

功能

资源

访问所有端点的架构文档：

• schema://games - 比赛信息和比分
• schema://records - 球队赛季战绩
• schema://games/teams - 详细的球队比赛数据
• schema://plays - 逐场比赛信息
• schema://drives - 推进回合摘要和结果
• schema://play/stats - 单次进攻统计数据
• schema://rankings - 各民意调查中的球队排名
• schema://metrics/wp/pregame - 赛前获胜概率
• schema://game/box/advanced - 高级比赛技术统计数据

工具

直接查询端点：

• get-games - 获取比赛数据
• get-records - 获取球队战绩
• get-games-teams - 访问球队比赛统计数据
• get-plays - 查询逐场比赛数据
• get-drives - 分析推进回合信息
• get-play-stats - 查看比赛统计数据
• get-rankings - 查看球队排名
• get-pregame-win-probability - 查看获胜概率
• get-advanced-box-score - 访问详细的比赛统计数据和分析

提示词

预先构建的分析模板：

• analyze-game - 获取特定比赛的详细分析
• analyze-team - 全面的单支球队分析
• analyze-trends - 分析整个赛季的趋势
• compare-teams - 比较两支球队的表现
• analyze-rivalry - 分析历史上的对决

API 限制

College Football Data API 可免费使用，但设有速率限制：

• 免费层级：每分钟请求次数有限
• CFBD Patreon 订阅者可享有更高的速率限制
• 使用高效的查询方式，避免触及限制
• 妥善处理速率限制错误

开发

项目结构

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

设置开发环境

1. 克隆仓库
2. 安装开发依赖项：

uv pip install -e ".[dev]"

3. 运行测试：

pytest

参与贡献

1. 复刻仓库
2. 创建功能分支
3. 提交更改
4. 推送到你的复刻仓库
5. 提交拉取请求

故障排除

常见问题

1. API 密钥错误

   • 确认已在 .env 和 claude_desktop_config.json 文件中正确设置 API 密钥
   • 在 collegefootballdata.com 检查密钥是否有效

2. 速率限制

   • 尽可能错开请求
   • 考虑订阅 Patreon 以获得更高的限制
   • 为频繁访问的数据实现缓存

3. 连接问题

   • 确认网络连接正常
   • 在 collegefootballdata.com 检查 API 状态
   • 确保代码中有适当的错误处理

获取帮助

• 在 GitHub 上提交问题
• 查看 API 文档
• 查看 College Football Data Discord

许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

致谢

• 感谢 College Football Data 提供 API
• 感谢 Model Context Protocol 提供 MCP 规范