大学橄榄球数据 MCP 服务器

一个 MCP 服务器实现，提供对大学橄榄球统计数据的访问，这些数据来源于 College Football Data API，并在 Claude Desktop 中使用。

概述

这个模型上下文协议 (MCP) 服务器使 AI 助手和应用程序能够：

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

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

示例输出

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

答：让我来帮你找到 2014 年最大的 FCS 冷门。我将查看比赛数据，重点关注 FCS 球队之间的比赛，这些比赛在球队实力方面存在显着差距，并且结果出乎意料。

数据显示，2014 年 FCS 比赛中出现了几次值得注意的冷门，但其中一个突出的是 2014 年 9 月 6 日，Eastern Washington 以 52-59 击败 Washington。这尤其重要，因为：

1. Washington 是一支来自 Pac-12 联盟的 FBS 球队
2. 比赛在 Washington 的主场（Husky Stadium）进行
3. 根据赛后统计数据，Eastern Washington 的获胜概率仅为 1.4%
4. Eastern Washington 获得的 59 分是 FCS 球队对阵 Pac-12 对手时获得的最高分
5. Washington 在比赛开始前被看好能获得多个达阵

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

• North Dakota State 以 34-14 击败 Iowa State
• Bethune-Cookman 以 14-12 击败 FIU
• Northern Iowa 差点击败 Iowa（以 31-23 输掉比赛）

然而，考虑到以下因素，Eastern Washington 击败 Washington 似乎是 2014 年 FCS 赛季最大的冷门：

• 级别差异（FCS vs FBS）
• FBS 对手的实力（五大联盟）
• 弱队的得分差距和进攻表现
• 作为 FCS 球队对阵五大联盟球队的最高得分胜利之一的历史意义
• 发生在客场，在充满敌意的环境中

前提条件

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

安装

通过 Smithery 安装

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

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  # 在 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  # 在 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

重启后，您应该在文本框的右下角看到一个小锤子图标。如果将鼠标悬停在图标上，您将看到可用的 MCP 工具的数量。

安装后更新

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. Fork 存储库
2. 创建一个功能分支
3. 提交您的更改
4. 推送到您的 fork
5. 提交 pull request

故障排除

常见问题

1. API 密钥错误

   • 验证您的 API 密钥是否在 .env 和 claude_desktop_config.json 文件中正确设置
   • 在 collegefootballdata.com 上检查密钥是否有效

2. 速率限制

   • 尽可能间隔请求
   • 考虑 Patreon 订阅以获得更高的限制
   • 为经常访问的数据实施缓存

3. 连接问题

   • 验证互联网连接
   • 在 collegefootballdata.com 上检查 API 状态
   • 确保您的代码中包含适当的错误处理

获取帮助

• 在 GitHub 上打开一个 issue
• 查看 API 文档
• 查看 College Football Data Discord

许可证

此项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

致谢

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