Sports MCP

体育MCP服务器


一种模型上下文协议（MCP）服务器，可从ESPN的体育API中提供实时体育比分、时间表和比赛信息。该服务器使人工智能助手能够回答有关职业和大学联赛的比赛结果、赛程、团队表现和体育成绩的问题。

特性

• 🏀 实时分数和结果：获取游戏的实时分数和最终结果
• 📅 调度信息：查看即将到来的游戏和过去的游戏结果
• 🏆 联赛全面覆盖：支持27个以上的体育联盟
• 📊 详细游戏数据：球队统计数据、场地信息、转播细节等
• 🔧 MCP兼容：可与任何兼容MCP的AI助手配合使用

⚠️ 重要通知

该项目依赖于ESPN的未经证明的API。 此服务器使用的ESPN API没有正式文档，也没有得到ESPN的支持。像这样的：

• API可能会在未经通知的情况下更改，这可能会破坏功能
• API随时可能无法访问或受到限制
• 无法保证服务可用性或数据准确性
• 将此项目用于非商业目的，风险自负

这是一个为教育和个人使用而构建的非官方工具。

先决条件

• .NET 8.0 SDK或更高版本
• MCP兼容客户端（如Claude Desktop、Cline等）

安装

1.克隆和构建

git clone 
cd sports-mcp
dotnet build

2.配置设置

复制示例配置并使用ESPN API终结点进行更新：

cp appsettings.example.json appsettings.json

编辑 appsettings.json:

{
  "SportsApi": {
    "BaseUrl": "http://site.api.espn.com/apis/site/v2"
  }
}

3.配置您的MCP客户端

将服务器添加到MCP客户端配置中。对于Claude Desktop，编辑您的 claude_desktop_config.json:

视窗: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "sports": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "C:\\path\\to\\sports-mcp\\sports-mcp.csproj"
      ]
    }
  }
}

更新配置后重新启动MCP客户端。

用法

配置后，您可以向AI助手自然语言提问有关体育的问题：

• “昨天NBA的比分是多少？”
• “给我看今天的NFL比赛”
• “昨晚谁赢了湖人队的比赛？”
• “这个周末英超联赛的赛程是什么？”
• “给我2026年1月25日所有NBA比赛的分数”

可用工具

GetScoreboard

检索体育比分、赛程和比赛信息。

参数：

• sport （必填）：运动类型（足球、篮球、足球、棒球、曲棍球、网球、高尔夫、赛车）
• league （必填）：具体联赛或比赛
• date （可选）：结果或时间表的日期（ISO格式：YYYY-MM-DD）。如果省略，则默认为当前日期。

退货：

• 比赛/事件列表，包括比分、球队信息、状态、场地和转播细节
• 联赛信息
• 团队记录和统计
• 游戏状态（已计划、进行中、最终）

支持的体育和联赛

🏈 足球

• 国家橄榄球大联盟：国家足球联赛
• 大学足球：NCAA大学橄榄球

🏀 篮球

• 美国职业篮球联赛：美国国家篮球协会
• 美国女子职业篮球联盟：美国女子篮球协会
• 男子篮球：NCAA男子大学篮球
• 女子学院篮球：NCAA女子大学篮球

⚾ 棒球

• 美国职业棒球大联盟：美国职业棒球大联盟
• MenCollegeBaseball：NCAA男子大学棒球

⚽ 足球

• 英超联赛：英超联赛
• 英里：美国职业足球大联盟
• UEFAChampionsLeague：欧洲冠军联赛
• UEFA欧洲联盟：欧洲足球联赛

🏒 曲棍球

• 国家冰球联盟：国家冰球联盟
• 男子学院霍基：NCAA男子大学冰球
• 女子学院霍基：NCAA女子大学冰球

🎾 网球

• 三磷酸腺苷：职业网球协会
• 女子网球协会：女子网球协会

⛳ 高尔夫

• PGA：美国职业高尔夫球协会巡回赛
• 女子职业高尔夫球协会：LPGA巡回赛
• 欧洲之旅：DP世界巡回赛（欧洲巡回赛）

🏎️ 赛车

• 纳斯卡：纳斯卡杯系列赛
• 一层楼：F1

配置

使用应用程序设置

{
  "SportsApi": {
    "BaseUrl": "http://site.api.espn.com/apis/site/v2"
  }
}

使用环境变量

您可以使用环境变量覆盖配置：

Windows（PowerShell）：

$env:SportsApi__BaseUrl="http://site.api.espn.com/apis/site/v2"

Windows（命令提示符）：

set SportsApi__BaseUrl=http://site.api.espn.com/apis/site/v2

Linux/macOS：

export SportsApi__BaseUrl="http://site.api.espn.com/apis/site/v2"

发展

建筑

dotnet build

本地运行

dotnet run

测试

该项目包括一个全面的单元测试套件 sports-mcp.Tests 项目。测试使用 x单位 并覆盖服务器的所有主要组件。

运行测试

dotnet test

要运行详细的输出：

dotnet test --verbosity normal

测试覆盖率

测试套件包括：

• 体育与联赛菜单 (Models/SportsExtensionsTests.cs, Models/LeaguesExtensionsTests.cs)：验证每个 Sports 和 Leagues enum值映射到正确的ESPN API路径段。
• 记分牌DTO解析 (Models/ScoreboardDtoTests.cs)：验证所有数据类的JSON到DTO反序列化，包括联赛信息、比赛状态、场地详细信息、团队竞争对手、比赛事件和完整的记分板响应。对缺失可选字段、空事件列表和国际场馆等边缘情况进行测试。
• HTTP客户端扩展 (Extensions/HttpClientExtTests.cs)：测试JSON文档检索成功、HTTP错误传播以及请求URI构造正确。
• GetScoreboard工具 (Tools/SportsScoreboardToolTests.cs)：使用模拟HTTP处理程序进行端到端测试，验证正确的URL是否由sport/league/date参数构建，有效的响应是否被反序列化并序列化为缩进的JSON，以及HTTP或反序列化错误是否会产生格式良好的错误JSON响应。

测试方法

服务器使用MCP协议通过stdio进行通信，因此其各个组件都是单独测试的：

• 静态工具方法 (SportsScoreboardTool.GetScoreboard)接受 HttpClient 和 IOptions 作为显式参数，无需任何DI容器即可直接提供测试double。
• HTTP层 使用轻量级进程内伪造 HttpMessageHandler 子类。这避免了网络调用和第三方模拟库。
• 配置 通过以下方式提供 Microsoft.Extensions.Options.Options.Create()，保持测试的独立性。
• 内部类型 （例如。， HttpClientExt)通过以下方式接触测试项目 [InternalsVisibleTo("sports-mcp.Tests")] 在主要项目中。

项目结构

sports-mcp.Tests/
├── Extensions/
│   └── HttpClientExtTests.cs   # HTTP client extension tests
├── Models/
│   ├── LeaguesExtensionsTests.cs  # League enum mapping tests
│   ├── ScoreboardDtoTests.cs      # DTO JSON parsing tests
│   └── SportsExtensionsTests.cs   # Sport enum mapping tests
└── Tools/
    └── SportsScoreboardToolTests.cs  # GetScoreboard tool tests

项目结构

sports-mcp/
├── Extensions/          # HTTP client extensions
├── Models/             # Data models and enums
│   ├── Sports.cs       # Sport type enums
│   ├── Leagues.cs      # League enums
│   └── ScoreboardDto.cs # Response DTOs
├── Options/            # Configuration options
├── Tools/              # MCP tool implementations
│   └── SportsScoreboardTool.cs
├── Program.cs          # Application entry point
└── appsettings.json    # Configuration file

响应格式

服务器返回结构化JSON数据，包括：

{
  "Events": [
    {
      "Id": "401810505",
      "Name": "Sacramento Kings at Detroit Pistons",
      "ShortName": "SAC @ DET",
      "Date": "2026-01-25T20:00:00Z",
      "Status": {
        "Clock": 0,
        "DisplayClock": "0:00",
        "Period": 4,
        "Type": {
          "State": "post",
          "Completed": true,
          "Detail": "Final"
        }
      },
      "Competitors": [
        {
          "Team": {
            "DisplayName": "Detroit Pistons",
            "Abbreviation": "DET",
            "Logo": "https://..."
          },
          "Score": "139",
          "Winner": true,
          "HomeAway": "home",
          "Records": [...]
        }
      ],
      "Venue": {
        "FullName": "Little Caesars Arena",
        "Address": {
          "City": "Detroit",
          "State": "MI"
        }
      }
    }
  ],
  "League": {
    "Name": "National Basketball Association",
    "Abbreviation": "NBA"
  }
}

故障排除

“无法解析记分板数据”错误

如果API响应结构更改或包含意外数据，则可能发生此错误。最新的修复程序处理了预定游戏没有 winner 房地产还。

服务器未出现在MCP客户端中

1. 验证MCP客户端配置中的路径是否正确
2. 确保。NET 8.0 SDK已安装并位于您的PATH中
3. 检查一下 appsettings.json 存在并且配置正确
4. 配置更改后重新启动MCP客户端
5. 检查客户端日志中的启动错误

API超时或连接问题

• 验证互联网连接
• 检查ESPN API端点是否可访问： http://site.api.espn.com/apis/site/v2
• 确保没有防火墙阻止连接

数据源

该服务器从ESPN的公共体育API端点检索数据。数据按原样从ESPN的服务中提供。

许可证

该项目根据 MIT许可证.

贡献

欢迎投稿！请随时提交问题或拉取请求。

致谢

• 使用 模型上下文协议
• 体育数据由 ESPN API