BALLDONTLIE Sports MCP Server

这是一个提供全面体育数据访问的Model Context Protocol (MCP)服务器，数据来源于BALLDONTLIE API，包括NBA、WNBA、NFL、MLB、EPL、NHL、NCAAF和NCAAB的统计数据、球员信息、比赛数据等。

特性

• 120+ 体育端点：完全访问所有BALLDONTLIE API端点
• 8大主要体育项目：NBA、WNBA、NFL、MLB、EPL、NHL、NCAAF、NCAAB
• 全面的数据：球队、球员、比赛、统计数据、排名、伤病情况、投注赔率及高级分析
• 认证：无缝API密钥转发到后端
• 分页：完全支持基于游标的分页
• 错误处理：适当的错误转发和处理
• TypeScript：完整的类型安全性和IntelliSense支持

安装

npm install @balldontlie/mcp-server

快速开始

1. 获取API密钥

在BALLDONTLIE注册以获取您的免费API密钥。

2. 配置MCP客户端

方案A：使用托管远程服务器（推荐）

添加到您的MCP客户端配置（例如，Claude Desktop）以使用托管服务器：

{
  "mcpServers": {
    "balldontlie-api": {
      "url": "https://mcp.balldontlie.io/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "<YOUR_BALLDONTLIE_API_KEY>"
      }
    }
  }
}

将<YOUR_BALLDONTLIE_API_KEY>替换为您从BALLDONTLIE获得的实际API密钥。

方案B：从源代码运行

克隆并从源代码运行：

git clone https://github.com/balldontlie-api/mcp-server.git
cd mcp-server
npm install
npm run build
npm start

配置您的MCP客户端连接到本地服务器：

{
  "mcpServers": {
    "balldontlie-api": {
      "url": "http://localhost:3000/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "<YOUR_BALLDONTLIE_API_KEY>"
      }
    }
  }
}

3. 在您的MCP客户端中使用

服务器将自动提供所有可用工具。您可以向AI助手询问如下问题：

• "获取当前NBA排名"
• "显示勒布朗·詹姆斯的赛季统计数据"
• "今天有哪些NFL比赛？"
• "获取曼联最近的英超比赛"
• "显示阿雅·威尔逊的WNBA赛季统计数据"
• "当前WNBA排名是什么？"
• "显示NCAAB锦标赛对阵表"
• "获取今晚NBA比赛的投注赔率"

环境变量

变量名	默认值	描述
PORT	3000	当地运行时的服务器端口
BACKEND_API_URL	https://api.balldontlie.io	BALLDONTLIE API基础URL
API_TIMEOUT	30000	请求超时时间（毫秒）
LOG_LEVEL	info	日志级别（error, warn, info, debug）
NODE_ENV	development	环境（development, production, test）
ENABLE_DEBUG	false	启用调试日志
ENABLE_TRACING	false	启用DataDog APM追踪（需要DD_AGENT_HOST）
DD_AGENT_HOST	-	DataDog代理主机名用于APM追踪
DD_PROFILING_ENABLED	false	启用DataDog性能分析
SERVICE_VERSION	1.0.0	追踪的服务版本

可用工具

NBA（16个工具）

工具	描述	参数
nba_get_teams	获取所有NBA球队	division, conference
nba_get_team_by_id	获取特定NBA球队	id (必需)
nba_get_players	获取NBA球员（可筛选）	search, first_name, last_name, team_ids, player_ids, 分页
nba_get_player_by_id	获取特定NBA球员	id (必需)
nba_get_active_players	获取活跃NBA球员	同 nba_get_players
nba_get_games	获取NBA比赛	dates, seasons, team_ids, postseason, start_date, end_date, 分页
nba_get_game_by_id	获取特定NBA比赛	id (必需)
nba_get_stats	获取NBA统计数据	dates, seasons, team_ids, player_ids, game_ids, postseason, 分页
nba_get_season_averages	获取赛季平均数	season (必需), category (必需), type (必需), player_ids, season_type
nba_get_advanced_stats	获取高级统计数据	同 nba_get_stats
nba_get_box_scores	获取比赛得分统计	dates, seasons, team_ids, game_ids, postseason, 分页
nba_get_live_box_scores	获取实时比赛得分统计	同 nba_get_box_scores
nba_get_standings	获取球队排名	season, conference, division
nba_get_leaders	获取统计数据领先者	season, stat_type, per_page
nba_get_player_injuries	获取球员伤病情况	player_ids, team_ids, 分页
nba_get_betting_odds	获取比赛投注赔率	dates, game_ids, 分页

NFL（15个工具）

工具	描述	参数
nfl_get_teams	获取所有NFL球队	division, conference
nfl_get_team_by_id	获取特定NFL球队	id (必需)
nfl_get_players	获取NFL球员	search, first_name, last_name, team_ids, player_ids, position, 分页
nfl_get_player_by_id	获取特定NFL球员	id (必需)
nfl_get_active_players	获取活跃NFL球员	同 nfl_get_players
nfl_get_games	获取NFL比赛	dates, seasons, team_ids, weeks, postseason, start_date, end_date, 分页
nfl_get_game_by_id	获取特定NFL比赛	id (必需)
nfl_get_stats	获取NFL统计数据	dates, seasons, team_ids, player_ids, game_ids, weeks, postseason, 分页
nfl_get_season_stats	获取赛季统计数据	season, player_ids, team_ids, postseason, 分页
nfl_get_standings	获取球队排名	season, conference, division
nfl_get_player_injuries	获取球员伤病情况	player_ids, team_ids, 分页
nfl_get_advanced_rushing_stats	获取高级冲球统计数据	season, week, player_ids, team_ids, position, 分页
nfl_get_advanced_passing_stats	获取高级传球统计数据	同 nfl_get_advanced_rushing_stats
nfl_get_advanced_receiving_stats	获取高级接球统计数据	同 nfl_get_advanced_rushing_stats
nfl_get_betting_odds	获取比赛投注赔率	season, week, game_ids, 分页

MLB（12个工具）

工具	描述	参数
mlb_get_teams	获取所有MLB球队	division, league
mlb_get_team_by_id	获取特定MLB球队	id (必需)
mlb_get_players	获取MLB球员	search, first_name, last_name, team_ids, player_ids, position, active, 分页
mlb_get_player_by_id	获取特定MLB球员	id (必需)
mlb_get_active_players	获取活跃MLB球员	同 mlb_get_players
mlb_get_games	获取MLB比赛	dates, seasons, team_ids, postseason, start_date, end_date, 分页
mlb_get_game_by_id	获取特定MLB比赛	id (必需)
mlb_get_stats	获取MLB统计数据	dates, seasons, team_ids, player_ids, game_ids, postseason, 分页
mlb_get_season_stats	获取赛季统计数据	season, player_ids, team_ids, postseason, 分页
mlb_get_team_season_stats	获取球队赛季统计数据	season, team_ids, postseason, 分页
mlb_get_standings	获取球队排名	season, league, division
mlb_get_player_injuries	获取球员伤病情况	player_ids, team_ids, 分页

EPL（16个工具）

工具	描述	参数
epl_get_teams	获取所有EPL球队	分页
epl_get_team_by_id	获取特定EPL球队	id (必需)
epl_get_team_players	获取球队球员	id (必需), 分页
epl_get_team_season_stats	获取球队赛季统计数据	id (必需), season, stat_types
epl_get_team_stats_leaders	获取球队统计数据领先者	season, stat_type, per_page
epl_get_standings	获取EPL排名	season
epl_get_players	获取EPL球员	search, team_ids, player_ids, position, 分页
epl_get_player_by_id	获取特定EPL球员	id (必需)
epl_get_player_season_stats	获取球员赛季统计数据	id (必需), season, stat_types
epl_get_player_stats_leaders	获取球员统计数据领先者	season, stat_type, per_page
epl_get_games	获取EPL比赛	dates, seasons, team_ids, weeks, start_date, end_date, 分页
epl_get_game_by_id	获取特定EPL比赛	id (必需)
epl_get_game_lineups	获取比赛阵容	id (必需)
epl_get_game_goals	获取比赛进球	id (必需)
epl_get_game_team_stats	获取比赛球队统计数据	id (必需)
epl_get_game_player_stats	获取比赛球员统计数据	id (必需)

NHL（12个工具）

工具	描述	参数
nhl_get_teams	获取所有NHL球队	conference, division, 分页
nhl_get_team_by_id	获取特定NHL球队	id (必需)
nhl_get_team_season_stats	获取球队赛季统计数据	id (必需), season
nhl_get_team_stats_leaders	获取球队统计数据领先者	season, stat_type, per_page
nhl_get_players	获取NHL球员	search, team_ids, player_ids, position, 分页
nhl_get_player_by_id	获取特定NHL球员	id (必需)
nhl_get_player_season_stats	获取球员赛季统计数据	id (必需), season
nhl_get_player_stats_leaders	获取球员统计数据领先者	season, stat_type, per_page
nhl_get_games	获取NHL比赛	dates, seasons, team_ids, season_type, start_date, end_date, 分页
nhl_get_game_by_id	获取特定NHL比赛	id (必需)
nhl_get_standings	获取NHL排名	season, conference, division
nhl_get_box_scores	获取NHL比赛得分统计	dates, seasons, team_ids, game_ids, season_type, 分页

WNBA（14个工具）

工具	描述	参数
wnba_get_teams	获取所有WNBA球队	conference
wnba_get_team_by_id	获取特定WNBA球队	id (必需)
wnba_get_players	获取WNBA球员	search, first_name, last_name, team_ids, player_ids, 分页
wnba_get_player_by_id	获取特定WNBA球员	id (必需)
wnba_get_active_players	获取活跃WNBA球员	同 wnba_get_players
wnba_get_games	获取WNBA比赛	dates, seasons, team_ids, season_type, start_date, end_date, 分页
wnba_get_game_by_id	获取特定WNBA比赛	id (必需)
wnba_get_player_stats	获取球员比赛统计数据	game_ids, dates, seasons, player_ids, team_ids, 分页
wnba_get_team_stats	获取球队比赛统计数据	game_ids, dates, seasons, team_ids, 分页
wnba_get_player_season_stats	获取球员赛季统计数据	player_ids, team_ids, season, season_type, 分页
wnba_get_team_season_stats	获取球队赛季统计数据	team_ids, season, season_type, 分页
wnba_get_standings	获取WNBA排名	season, conference
wnba_get_player_injuries	获取球员伤病情况	player_ids, team_ids, 分页
wnba_get_plays	获取逐场数据	game_id (必需)

NCAAF（17个工具）

工具	描述	参数
ncaaf_get_conferences	获取所有NCAAF联盟	-
ncaaf_get_conference_by_id	获取特定NCAAF联盟	id (必需)
ncaaf_get_teams	获取所有NCAAF球队	conference, 分页
ncaaf_get_team_by_id	获取特定NCAAF球队	id (必需)
ncaaf_get_players	获取NCAAF球员	search, first_name, last_name, team_ids, player_ids, position, 分页
ncaaf_get_active_players	获取活跃NCAAF球员	同 ncaaf_get_players
ncaaf_get_player_by_id	获取特定NCAAF球员	id (必需)
ncaaf_get_standings	获取NCAAF排名	season, conference_id, 分页
ncaaf_get_games	获取NCAAF比赛	dates, seasons, team_ids, weeks, start_date, end_date, 分页
ncaaf_get_game_by_id	获取特定NCAAF比赛	id (必需)
ncaaf_get_rankings	获取NCAAF排名	season, week, 分页
`ncaaf_get_plays