# Valorant MCP Server

An MCP (Model Context Protocol) server that exposes Valorant match analysis tools. Connect it to Claude (or any MCP-compatible client) to fetch and analyze player stats, match history, agent performance, and more.

Powered by [Henrik's Unofficial Valorant API](https://docs.henrikdev.xyz/valorant/general).

## Tools

| Tool | Description |
|------|-------------|
| `get_player_info` | Fetch basic account info for a Riot ID |
| `get_match_history` | Recent match history with stats for you and teammates (competitive by default; also supports unrated, deathmatch, swiftplay, spikerush, premier) |
| `get_match_details` | Full breakdown of a specific match. `summary` view (default): per-player stats, team totals, kill list, round results, economy. `narrative` view: round-by-round timeline with named map zones (A Site, Mid, B Long, etc.) and event tags (entry, first_blood, trade, rotation) |
| `get_agent_stats` | Aggregated per-agent stats: win rate, avg KDA, avg score |
| `get_map_stats` | Aggregated per-map stats: win rate, avg score |
| `get_weapon_stats` | Weapon usage stats: kills per weapon, usage percentage |
| `get_rank_progression` | Current rank, elo, peak rank, and season history |

## Setup

### Prerequisites

- [uv](https://docs.astral.sh/uv/) package manager:
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
  (Windows: `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"`)
- A [Henrik API key](https://api.henrikdev.xyz/dashboard/)

### Claude Code

```bash
claude mcp add valorant-analyzer -e HENRIK_API_KEY=your-key-here -- uvx valorant-mcp
```

### Claude Desktop

Add to your Claude Desktop config:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "valorant-analyzer": {
      "command": "uvx",
      "args": ["valorant-mcp"],
      "env": {
        "HENRIK_API_KEY": "your-key-here"
      }
    }
  }
}
```

## Local Development

```bash
git clone https://github.com/SeijiMatsumoto/valorant-mcp.git
cd valorant-mcp
uv sync
```

Create a `.env` file in the project root:

```
HENRIK_API_KEY=your-api-key-here
```

### Run the server

```bash
uv run valorant-mcp
```

### Test with MCP Inspector

```bash
mcp dev src/valorant_mcp/server.py
```

### Run tests

```bash
uv run pytest src/valorant_mcp/tests/ -v
```

## Tech Stack

- [MCP Python SDK (FastMCP)](https://github.com/modelcontextprotocol/python-sdk) — server framework
- [httpx](https://www.python-httpx.org/) — async HTTP client
- [Pydantic](https://docs.pydantic.dev/) — data validation
- [uv](https://docs.astral.sh/uv/) — package management

## License

MIT