Skip to main content
Glama
Valorant MCP Server
by bluebot-609

Valorant MCP Server

A Model Context Protocol (MCP) server that provides access to Valorant game data using the unofficial Valorant API.

Features

  • Player Information: Get account details, MMR, and match history

  • Match Data: Detailed match information and statistics

  • Game Content: Agents, maps, weapons, and other game assets

  • Service Status: Check Valorant service status and maintenance

  • Leaderboards: Competitive rankings and leaderboards

Related MCP server: MCP Riot Server

Prerequisites

  • Python 3.11 or higher

  • A Valorant API key from HenrikDev API

  • Internet connection for API requests

Installation

No local environment setup required. uvx runs the packaged console script directly.

# 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/<your-username>/valorant-mcp-server.git valorant-mcp-server

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

Optionally set an API key in the environment first (or use the set_api_key tool at runtime):

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

Option 2: Local UV/Pip environment

# Clone and setup
git clone https://github.com/<your-username>/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

Usage

Running the Server

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

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

Note: The server will start and wait for MCP client connections. It will show a warning if no API key is set, but you can still use the set_api_key tool to configure it at runtime.

Using with MCP Clients

Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

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

Cline (VS Code Extension)

Add to your Cline configuration:

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

Generic MCP Client

Use the packaged command with uvx:

uvx --from git+https://github.com/<your-username>/valorant-mcp-server.git valorant-mcp-server

Available Tools

  • get_account_details(name, tag, region="na"): Basic account info (PUUID, level, card, region).

  • get_match_history_by_name(name, tag, region="na", size=10): Recent matches with per-game stats.

  • get_match_details(match_id, region="na"): Full details for a specific match.

  • get_mmr_details_by_name(name, tag, region="na"): Current competitive tier, ELO, RR.

  • get_mmr_history_by_name(name, tag, region="na", size=10): Competitive MMR history with match IDs.

  • get_lifetime_matches_by_name(name, tag, region="na", mode=None, map_filter=None, page=1, size=20): Aggregate lifetime stats and list of matches.

  • get_leaderboard(region="na", season="e8a1"): Top players for a region/season.

  • get_content(region="na"): Agents, maps, and other content.

  • get_status(region="na"): Service status and incidents.

  • set_api_key(api_key_input): Set HenrikDev API key at runtime.

  • get_detailed_competitive_analysis(name, tag, region="na", match_count=10): Correlate MMR history with match stats.

  • find_leaderboard_position(name, tag, region="na", season="e8a1"): Locate a player on the leaderboard (Immortal 3+).

Testing

You can validate connectivity by launching the server via uvx and connecting from your MCP client (Claude Desktop/Cline/Cursor). Use the get_status and get_content tools to confirm responses.

Configuration

Environment Variables

  • VALORANT_API_KEY: Your Valorant API key (required)

API Key Setup

You can set your API key in two ways:

  1. Environment Variable: Set VALORANT_API_KEY in your environment

  2. Runtime: Use the set_api_key tool to configure it at runtime

Project Structure

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 Integration

This server uses:

Error Handling

The server includes comprehensive error handling for:

  • Invalid API keys

  • Rate limiting

  • Network errors

  • Invalid player names or regions

  • Service unavailability

All errors are logged and returned in a structured format.

Development

Adding New Tools

To add new Valorant API endpoints:

  1. Create a new function decorated with @mcp.tool()

  2. Add proper error handling with try/catch blocks

  3. Use the global valo_api instance

  4. Return structured data using Pydantic models

  5. Update this README with the new tool documentation

Code Quality

# 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

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

License

This project is licensed under the MIT License.

Acknowledgments

Available Tools

12 tools
find_leaderboard_positionA

Find a player's position on the competitive leaderboard.

Searches leaderboard and provides position + nearby players. Only works for Immortal 3+ players.

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam) season: Season identifier (default: e8a1)

Returns: Leaderboard position, rank, nearby players

Inputs: tag (required), name (required), region, season. Returns: object

get_account_detailsA

Get account details for a Valorant player.

Essential tool for getting PUUID and account information.

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam)

Returns: PUUID, account level, player card, region info

Inputs: tag (required), name (required), region. Returns: object

get_contentC

Get game content (agents, maps, weapons).

Essential for understanding game elements.

Args: region: Region code (ap, na, eu, kr, br, latam)

Returns: All agents, maps, and game content

Inputs: region. Returns: object

get_detailed_competitive_analysisA

Get comprehensive competitive analysis by combining MMR history + match details.

This is the most powerful tool for competitive insights. Combines two different API endpoints to correlate performance with MMR changes.

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam) match_count: Number of matches to analyze (default: 10, max: 20)

Returns: Detailed competitive matches with performance + MMR correlation

Inputs: tag (required), name (required), region, match_count. Returns: object

get_leaderboardA

Get the competitive leaderboard for a region.

Shows top players in region/season.

Args: region: Region code (ap, na, eu, kr, br, latam) season: Season identifier (default: e8a1)

Returns: List of top players with rankings and ratings

Inputs: region, season. Returns: object

get_lifetime_matches_by_nameA

Get lifetime match statistics (different API endpoint).

Provides aggregate lifetime stats and match history.

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam) mode: Optional game mode filter map_filter: Optional map filter page: Page number (default: 1) size: Matches per page (default: 20)

Returns: Lifetime stats and match list

Inputs: tag (required), name (required), mode, page, +3 more. Returns: object

get_match_detailsA

Get detailed information about a specific match.

Provides comprehensive match data including all players' stats.

Args: match_id: Match identifier region: Region code (ap, na, eu, kr, br, latam)

Returns: Match details with all players, rounds, scores

Inputs: match_id (required), region. Returns: object

get_match_history_by_nameA

Get recent match history for a player.

Returns matches across all game modes with detailed stats.

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam) size: Number of matches (default: 10, max: 20)

Returns: List of matches with kills, deaths, assists, agents, maps, scores

Inputs: tag (required), name (required), size, region. Returns: object

get_mmr_details_by_nameA

Get current MMR and rank for a player.

Provides current competitive standing.

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam)

Returns: Current rank, ELO, RR, last game MMR change

Inputs: tag (required), name (required), region. Returns: object

get_mmr_history_by_nameA

Get MMR history with match IDs and maps.

Essential for competitive analysis - includes match IDs for each game!

Args: name: Player's in-game name tag: Player's tag region: Region code (ap, na, eu, kr, br, latam) size: Number of history entries (default: 10, max: 20)

Returns: MMR history with match IDs, maps, rank changes, dates

Inputs: tag (required), name (required), size, region. Returns: object

get_statusA

Get Valorant service status.

Checks for maintenance and incidents.

Args: region: Region code (ap, na, eu, kr, br, latam)

Returns: Service status, maintenance windows, incidents

Inputs: region. Returns: object

set_api_keyA

Set the API key for Valorant API requests.

Required for authentication.

Args: api_key_input: Your HenrikDev API key

Returns: Confirmation message

Inputs: api_key_input (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools target distinct resources/actions. There is slight overlap between get_match_history_by_name and get_lifetime_matches_by_name, but descriptions clarify the difference (recent vs lifetime aggregate). Otherwise, tools are clearly distinct.

    Naming Consistency4/5

    Predominantly uses get_<resource>_<detail> pattern with consistent snake_case. Minor deviations with set_api_key and find_leaderboard_position, but overall the pattern is predictable.

    Tool Count5/5

    12 tools is well-scoped for a Valorant stats API, covering accounts, matches, MMR, leaderboard, content, status, and auth. No redundancy.

    Completeness5/5

    The tool surface is comprehensive for read-only stat retrieval: account, recent/lifetime matches, match details, MMR details/history, leaderboard access, content, status, and a composite analysis tool. No obvious dead ends; all tools connect (e.g., MMR history returns match IDs for match details).

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides Formula One data and statistics through a Model Context Protocol interface, allowing users to access race calendars, session results, driver statistics, telemetry data, and championship standings.
      8
      11
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A community-developed Model Context Protocol server that integrates with the Riot Games API to provide League of Legends data, enabling AI assistants to retrieve player information, ranked stats, champion mastery, and match summaries through natural language queries.
      5
      27
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      A Model Context Protocol implementation that enables AI agents to retrieve game data from OP.GG for League of Legends, Teamfight Tactics, Valorant, and esports through function calling.
      24
      106
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables access to MLB Stats API data including game schedules, results, team information, and player lookups with fuzzy matching support through the Model Context Protocol.
      3
      7
      MIT