hkaanengin/opendota-mcp-server

A Model Context Protocol (MCP) server that provides seamless access to the OpenDota API for querying Dota 2 player statistics, match data, and hero information through AI assistants like Claude.

Features

• 20+ Tools across 5 categories for comprehensive Dota 2 data access
• Natural Language Support - Fuzzy matching for hero names, lane positions, and stat fields
• Dual Transport - Supports both stdio (local) and HTTP (remote) modes
• Rate Limiting - Built-in protection respecting OpenDota API limits
• Reference Data Caching - Fast lookups with local hero/item data

Available Tools

Player Tools (6 tools)

Query player statistics, win/loss records, hero preferences, and performance metrics:

• get_player_info - Get player profile, win rate, and favorite heroes
• get_player_win_loss - Win/loss stats with advanced filtering
• get_heroes_played - Detailed statistics for all heroes played
• get_player_peers - Find frequent teammates
• get_player_totals - Aggregated player statistics
• get_player_histograms - Distribution of matches across statistical fields

Hero Tools (4 tools)

Access hero information, matchups, and item builds:

• get_heroes - List all heroes with attributes
• get_hero_matchups - Matchup data and win rates
• get_hero_item_popularity - Popular item builds by game phase
• get_hero_stats - Aggregated hero statistics and pick rates

Match Tools (3 tools)

Retrieve detailed match information and parsed data:

• get_match_details - Comprehensive match information
• get_parsed_match_details - Parsed match data with advanced analytics
• get_player_recent_matches - Recent matches for a player

Lookup Tools (4 tools)

Convert names to IDs with fuzzy matching:

• get_hero_id_by_name - Hero name → ID (handles typos)
• get_hero_by_id - Get hero details by ID
• convert_lane_name_to_id - Lane/position → lane_role ID
• resolve_time_name - Time period names → OpenDota filter parameters

Misc Tools (3 tools)

Search and utility functions:

• search_players - Search for players by name
• get_constants - Get OpenDota constants and reference data
• get_player_counts - Get player count by rank tier

Installation

Prerequisites

• Python 3.10 or higher
• pip package manager

Install from Source

# Clone the repository
git clone https://github.com/hkaanengin/opendota-mcp-server.git
cd opendota-mcp-server

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"

# Or install runtime only
pip install -e .

Usage

Option 1: Local Server (stdio mode)

Best for Claude Desktop integration on your local machine.

Using Claude Desktop

Config file location:

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

Recommended: Using the installed command

After running pip install -e ., add to your claude_desktop_config.json:

{
  "mcpServers": {
    "opendota": {
      "command": "/path/to/your/opendota-mcp-server/.venv/bin/opendota-mcp"
    }
  }
}

Note: Replace /path/to/your/opendota-mcp-server with the actual path where you cloned this repository. On macOS/Linux, run pwd in the project directory to find this path. On Windows, run cd to see the full path.

Alternative: Using Python module directly

{
  "mcpServers": {
    "opendota": {
      "command": "/path/to/your/opendota-mcp-server/.venv/bin/python",
      "args": ["-m", "opendota_mcp.server"]
    }
  }
}

Alternative: Using the shell script

{
  "mcpServers": {
    "opendota": {
      "command": "/path/to/your/opendota-mcp-server/start_mcp.sh"
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "opendota": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "MCP_TRANSPORT=stdio",
        "hkaanengin/opendota-mcp-server:latest"
      ]
    }
  }
}

After updating the config:

1. Save the file
2. Restart Claude Desktop completely
3. Start a new conversation
4. Your OpenDota tools should now be available!

Manual Testing

# Run the server directly
opendota-mcp

# Or using Python module
python -m opendota_mcp.server

# Or using the shell script
./start_mcp.sh

Option 2: Remote Server (HTTP mode)

Access a deployed server from anywhere.

Public Server

Use the publicly deployed server at:

https://opendota-mcp-server-jylza6gata-ew.a.run.app/mcp

Claude Desktop (Remote Connection)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "opendota": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-remote-http",
        "https://opendota-mcp-server-jylza6gata-ew.a.run.app/mcp"
      ]
    }
  }
}

Claude.ai Web Interface

1. Go to Claude.ai → Settings → MCP Servers
2. Click "Add Server"
3. Enter Server URL: https://opendota-mcp-server-jylza6gata-ew.a.run.app/mcp
4. Save and start chatting!

Option 3: Deploy Your Own

Deploy to Google Cloud Run or any container platform:

# Build Docker image
docker build -t opendota-mcp-server .

# Run in HTTP mode
docker run -p 8080:8080 \
  -e MCP_TRANSPORT=http \
  -e PORT=8080 \
  opendota-mcp-server

Configuration

Environment Variables

Create a .env file in the project root (or copy from .env.example):

# OpenDota API Key (optional)
# Get your API key from: https://www.opendota.com/api-keys
OPENDOTA_API_KEY=

# Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

# Transport mode (stdio or http)
MCP_TRANSPORT=stdio

# HTTP server port (for HTTP mode)
PORT=8080

OpenDota API Key (Optional)

An API key is optional but recommended for higher rate limits and better performance.

Rate Limits:

• Without API key: 60 requests/minute (anonymous)
• With API key: Higher limits for registered users

How to get an API key:

1. Visit https://www.opendota.com/api-keys
2. Sign in with your Steam account
3. Click "Create API Key"
4. Copy the generated API key
5. Add it to your .env file:

   OPENDOTA_API_KEY=your-api-key-here
   

6. Restart the server

The server will automatically detect and use the API key when configured. You'll see a confirmation message in the logs:

✅ OpenDota API key configured (higher rate limits enabled)

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Acknowledgments

• OpenDota for providing the excellent Dota 2 API
• FastMCP for the MCP framework
• The Model Context Protocol team at Anthropic
• The Dota 2 community

Support

For issues, questions, or contributions:

• Open an issue on GitHub
• Check existing issues for solutions
• Review the OpenDota API documentation

---

Made with ❤️ for the Dota 2 community