MCP 服务端 (Model Context Protocol)

VLRdevAPI 原生内置 Model Context Protocol (MCP) 服务端，可将各类大语言模型应用、代码辅助 Agent 以及对话客户端直接连接至来自 vlr.gg 的实时无畏契约 (Valorant) 电竞赛事数据库。

借助覆盖赛程、系列赛、战队、选手、锦标赛、新闻资讯以及高阶复合情报的 40 项专用工具，AI 模型无需编写任何自定义爬虫代码，即可轻松查询实时赛程、核算两队历史交锋战绩、评估选手的特工池评分并分析对局的逐回合经济局势。

安装Copy Anchor Link

MCP 服务端已作为库的可选依赖拓展提供：

# 仅安装 MCP 服务端所需依赖
pip install "vlrdevapi[mcp]"

# 或安装包含数据科学与 MCP 的全量拓展包
pip install "vlrdevapi[all]"

启动服务端Copy Anchor Link

服务端遵循 MCP 协议标准，通过标准输入/输出 (stdio) 进行双向通信。

方式 1: 直接使用 CLI 命令Copy Anchor Link

vlrdevapi-mcp

方式 2: 使用 Python 模块命令Copy Anchor Link

python -m vlrdevapi.mcp.server

方式 3: 通过 uvx 实现免安装直接运行Copy Anchor Link

uvx --from "vlrdevapi[mcp]" vlrdevapi-mcp

客户端配置指南Copy Anchor Link

Claude DesktopCopy Anchor Link

将 vlrdevapi 添加至您的 Claude Desktop 配置文件中：

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

{
  "mcpServers": {
    "vlrdevapi": {
      "command": "uvx",
      "args": ["--from", "vlrdevapi[mcp]", "vlrdevapi-mcp"]
    }
  }
}

若您已在本地 Python 虚拟环境中安装了该库：

{
  "mcpServers": {
    "vlrdevapi": {
      "command": "/虚拟环境绝对路径/bin/vlrdevapi-mcp"
    }
  }
}

Cursor IDECopy Anchor Link

进入 Cursor 设置 → Features → MCP Servers，添加新服务端，或直接配置工作区根目录下的 .cursor/mcp.json：

{
  "mcpServers": {
    "vlrdevapi": {
      "command": "vlrdevapi-mcp"
    }
  }
}

Zed 编辑器Copy Anchor Link

在 Zed 的 settings.json 中配置：

{
  "context_servers": {
    "vlrdevapi": {
      "command": "vlrdevapi-mcp"
    }
  }
}

高阶复合工具 (专为多跳推理设计)Copy Anchor Link

除细粒度的基础接口外，VLRdevAPI 还专门提供了 8 项高阶复合工具，专为大模型的多步推理场景打造，单次调用即可返回完整综合情报：

完整工具清单 (40 项)Copy Anchor Link

比赛日程 (Matches)Copy Anchor Link

• matches_upcoming(page: int = 1, max_page: int = 0, return_all: bool = false): 查询即将开赛的赛程日程、对阵双方及开赛时间。
• matches_live(): 查询当前正在进行中的对局，包含实时比分与赛事信息。
• matches_completed(page: int = 1, max_page: int = 0, return_all: bool = false): 查询过往已完赛的历史比分、胜负队伍与完赛日期。

系列赛与单局 (Series & Games)Copy Anchor Link

• series_info(series_id: int): 比赛全貌详情，包含双方战队、对局日期、赛制 (BO3/BO5)、最终总比分与地图禁选 (Veto)。
• series_players(series_id: int, game_id: str = "all"): 全场或指定地图的选手综合表现数据（ACS、K/D、ADR、KAST）。
• series_rounds(series_id: int, game_id: int): 单局各回合攻守战况，包括回合胜方、胜利方式（拆包/歼敌等）与经济数据。
• series_performance(series_id: int, game_id: str = "all"): 选手击杀对战矩阵 (Kill Matrix) 与正面对决胜负数据。
• series_economy(series_id: int, game_id: str = "all"): 战队回合经济体系：银行结余、枪械装备价值与购买类型（全甲全枪/强起/纯保）。
• series_replay(series_id: int, game_id: int): 二维空间回放事件：小地图坐标点位、阵亡位置与装备载荷。
• series_vods(series_id: int): 官方赛事录像 VOD 链接、直播信号源与带时间戳的比赛切片。
• series_map_summary(series_id: int, game_id: str): 单张地图综合战报：回合经济演变、回放时间线与选手评分。

战队 (Teams)Copy Anchor Link

• team_info(team_id: int): 战队主页资料：全称、队标缩写、所属国家/地区、世界排名与社交媒体。
• team_roster(team_id: int): 现役队员名单，包含游戏 ID (IGN)、真实姓名与教练/分析师职位。
• team_stats(team_id: int, last_days: int | None = None, agent_composition: str = "none"): 地图胜率统计、攻守半场胜率（进攻/防守）以及特工阵容偏好。
• team_completed_matches(team_id: int, limit: int = 50, return_all: bool = false): 该战队的过往历史比赛记录。
• team_upcoming_matches(team_id: int): 该战队的未来预定赛程。
• team_transactions(team_id: int): 战队转会动态记录：队员引入、离队与人员角色变动。
• team_placements(team_id: int): 赛事名次榜单与获得的奖金总数。

选手 (Players)Copy Anchor Link

• player_info(player_id: int): 选手基本资料：比赛 ID、真实姓名、国籍与赛事总奖金收入。
• player_teams(player_id: int): 职业生涯效力战队轨迹与加入/离开时间。
• player_agents(player_id: int, timespan: str = "all"): 擅长特工数据分析（ACS、K/D、ADR、出场率），支持按周期过滤（30d、60d、90d、all）。
• player_matches(player_id: int, limit: int = 50): 个人出战比赛记录与单场个人表现评分。
• player_profile(player_id: int): 整合型选手大头照档案：个人生平、现役队伍与代表特工。
• player_placements(player_id: int): 选手个人在各项锦标赛中荣获的冠亚军及赛事名次。

赛事与锦标赛 (Events)Copy Anchor Link

• events_list(page: int = 1, tier: str = "all", region: str = "all", status: str | None = None): 浏览锦标赛列表，支持按赛事等级 (vct, vcl, gc, t3)、赛区与状态筛选。
• event_info(event_id: int): 赛事全貌档案：总奖金池、赛期安排、线下场馆与赛制。
• event_stages(event_id: int): 赛事赛段与晋级对阵图（小组赛、双败淘汰赛、总决赛）。
• event_teams(event_id: int): 各阶段参赛名单与出线战队。
• event_matches(event_id: int, stage: str | None = None, state: str = "all"): 锦标赛内部的既定赛程与比分结果。
• event_standings(event_id: int, stage: str | None = None): 最终名次排序、积分排名与奖金分配结果。

编辑部新闻 (News)Copy Anchor Link

• news_list(page: int = 1): 来自 vlr.gg 编辑部的最新无畏契约电竞赛事新闻列表。
• news_article(article_id: int): 完整新闻资讯文章：包含标题、作者、发布日期及 Markdown 排版正文。

响应序列化与架构设计Copy Anchor Link

所有工具返回的数据均直接使用 VLRdevAPI 内部高度优化的 ExportableModel.to_dict() 和 ExportableModel.to_json() 进行序列化：

1. 轻量级 JSON 载荷: 纯原生直接序列化，摒弃繁复冗余的中间包装，将大模型上下文窗口（Context Window）的 Token 开销降至最低。
2. 优雅的异常防护机制: 领域级别异常（如 NotFoundError 或 ValidationError）会被底层自动捕获并封装为标准 JSON 错误格式，绝不中断 MCP 通信管道：

   Copy Text

   {
     "error": "NotFound",
     "message": "Player with ID 99999999 not found"
   }

3. 严格的入参类型校验: 所有入参均符合基于 Pydantic 生成的标准 JSON Schema 规范，确保 Claude、GPT-4、Gemini 等主流大模型在工具调用时拥有极高的首发命中率。