Valorant MCP Server

Valorant MCP服务器

一种模型上下文协议（MCP）服务器，使用非官方的Valorant API提供对Valorant游戏数据的访问。

特性

• 玩家信息：获取帐户详细信息、MMR和匹配历史记录
• 匹配数据：详细的比赛信息和统计数据
• 游戏内容：代理、地图、武器和其他游戏资产
• 服务状态：检查Valorant服务状态和维护
• 排行榜：竞争性排名和排行榜

先决条件

• Python 3.11或更高版本
• 来自的Valorant API密钥 HenrikDev API
• API请求的Internet连接

安装

选项1：通过uvx运行（推荐）

无需设置本地环境。 uvx 直接运行打包的控制台脚本。

# Install UV if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run from GitHub (replace with your repo URL)
uvx --from git+https://github.com//valorant-mcp-server.git valorant-mcp-server

# Windows (PowerShell)
uvx --from git+https://github.com//valorant-mcp-server.git valorant-mcp-server

（可选）首先在环境中设置API键（或使用 set_api_key 运行时工具）：

export VALORANT_API_KEY="your_api_key_here"
uvx --from git+https://github.com//valorant-mcp-server.git valorant-mcp-server

选项2：局部UV/Pip环境

# Clone and setup
git clone https://github.com//valorant-mcp-server.git
cd valorant-mcp-server

# With UV
uv venv && . .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -r requirements.txt

# Or with pip
python -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt

# Environment
cp env.example .env  # Windows: copy env.example .env
# Edit .env and add your VALORANT_API_KEY

用法

运行服务器

# Recommended: uvx from git
uvx --from git+https://github.com//valorant-mcp-server.git valorant-mcp-server

# Locally (if you've installed deps)
python server.py

备注：服务器将启动并等待MCP客户端连接。如果没有设置API键，它将显示警告，但您仍然可以使用 set_api_key 在运行时配置它的工具。

与MCP客户端一起使用

克劳德桌面

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "valorant": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com//valorant-mcp-server.git", "valorant-mcp-server"],
      "env": {
        "VALORANT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cline（VS代码扩展）

添加到您的Cline配置：

{
  "mcpServers": {
    "valorant": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com//valorant-mcp-server.git", "valorant-mcp-server"],
      "env": {
        "VALORANT_API_KEY": "your_api_key_here"
      }
    }
  }
}

通用MCP客户端

将打包命令与uvx一起使用：

uvx --from git+https://github.com//valorant-mcp-server.git valorant-mcp-server

可用工具

• get_count_details（名称、标签、区域=“na”）：基本帐户信息（PUUID、级别、卡、地区）。
• get_match_history_by_name（名称、标签、区域=“na”，大小=10）：最近每场比赛的统计数据。
• get_match_details（match_id，region=“na”）：特定比赛的完整细节。
• get_mmr_details_by_name（名称、标签、区域=“na”）：当前竞争级别，ELO，RR。
• get_mmr_history_by_name（名称、标签、区域=“na”，大小=10）：具有比赛ID的竞争性MMR历史记录。
• get_life_matches_by_name（名称、标记、区域=“na”，模式=无，map_filter=无，页面=1，大小=20）：聚合生命周期统计数据和比赛列表。
• get_leaderboard（地区=“na”，季节=“e8a1”）：一个地区/赛季的顶级球员。
• get_content（区域=“na”）：代理、地图和其他内容。
• get_status（区域=“na”）：服务状态和事件。
• set_api_key（api_key_input）：在运行时设置HenrikDev API密钥。
• get_detired_competitive_analysis（名称、标签、区域=“na”，匹配计数=10）：将MMR历史与比赛统计数据相关联。
• find_leaderboard_position（名称、标签、地区=“na”，季节=“e8a1”）：在排行榜上找到一名玩家（不朽3+）。

测试

您可以通过以下方式启动服务器来验证连接 uvx 并从您的MCP客户端（Claude Desktop/Cline/Cursor）连接。使用 get_status 和 get_content 确认响应的工具。

配置

环境变量

• VALORANT_API_KEY：您的Valorant API密钥（必需）

API密钥设置

您可以通过两种方式设置API密钥：

1. 环境变量：设置 VALORANT_API_KEY 在您的环境中
2. 运行时：使用 set_api_key 运行时配置它的工具

项目结构

valorant-mcp-server/
├── server.py               # MCP server implementation (FastMCP)
├── pyproject.toml          # Package metadata + console script
├── requirements.txt        # Python dependencies (for local installs)
├── env.example             # Environment variables template
├── mcp-client-configs.md   # Client configuration examples
├── TOOLS_DOCUMENTATION.md  # Detailed tool docs
├── LICENSE                 # MIT License
├── .gitignore              # Git ignore file
└── README.md               # This file

API集成

此服务器使用：

• HenrikDev API -Valorant数据的核心API服务
• 直接HTTP请求 -Python为API调用请求库
• FastMCP -MCP框架

错误处理

该服务器包括全面的错误处理功能，用于：

• API密钥无效
• 速率限制
• 网络错误
• 玩家姓名或地区无效
• 服务不可用

所有错误都会被记录并以结构化格式返回。

发展

添加新工具

添加新的Valorant API端点：

1. 创建一个新功能，用 @mcp.tool()
2. 使用try/catch块添加适当的错误处理
3. 使用全局 valo_api 例子
4. 使用Pydantic模型返回结构化数据
5. 使用新的工具文档更新此README

代码质量

# Install development tools
pip install black isort mypy flake8

# Format code
black server.py test_server.py
isort server.py test_server.py

# Type checking
mypy server.py

# Linting
flake8 server.py test_server.py

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

该项目根据MIT许可证获得许可。

致谢

• 亨里克-3 用于非官方的Valorant API
• 莱曼玛 对于Python包装器
• FastMCP 对于MCP框架