OpenDota MCP Server

1# OpenDota MCP Server
2 
3A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides seamless access to the [OpenDota API](https://docs.opendota.com) for querying Dota 2 player statistics, match data, and hero information through AI assistants like Claude.
4 
5## Features
6 
7- **20+ Tools** across 5 categories for comprehensive Dota 2 data access
8- **Natural Language Support** - Fuzzy matching for hero names, lane positions, and stat fields
9- **Dual Transport** - Supports both stdio (local) and HTTP (remote) modes
10- **Rate Limiting** - Built-in protection respecting OpenDota API limits
11- **Reference Data Caching** - Fast lookups with local hero/item data
12 
13## Available Tools
14 
15### Player Tools (6 tools)
16Query player statistics, win/loss records, hero preferences, and performance metrics:
17- `get_player_info` - Get player profile, win rate, and favorite heroes
18- `get_player_win_loss` - Win/loss stats with advanced filtering
19- `get_heroes_played` - Detailed statistics for all heroes played
20- `get_player_peers` - Find frequent teammates
21- `get_player_totals` - Aggregated player statistics
22- `get_player_histograms` - Distribution of matches across statistical fields
23 
24### Hero Tools (4 tools)
25Access hero information, matchups, and item builds:
26- `get_heroes` - List all heroes with attributes
27- `get_hero_matchups` - Matchup data and win rates
28- `get_hero_item_popularity` - Popular item builds by game phase
29- `get_hero_stats` - Aggregated hero statistics and pick rates
30 
31### Match Tools (3 tools)
32Retrieve detailed match information and parsed data:
33- `get_match_details` - Comprehensive match information
34- `get_parsed_match_details` - Parsed match data with advanced analytics
35- `get_player_recent_matches` - Recent matches for a player
36 
37### Lookup Tools (4 tools)
38Convert names to IDs with fuzzy matching:
39- `get_hero_id_by_name` - Hero name → ID (handles typos)
40- `get_hero_by_id` - Get hero details by ID
41- `convert_lane_name_to_id` - Lane/position → lane_role ID
42- `resolve_time_name` - Time period names → OpenDota filter parameters
43 
44### Misc Tools (3 tools)
45Search and utility functions:
46- `search_players` - Search for players by name
47- `get_constants` - Get OpenDota constants and reference data
48- `get_player_counts` - Get player count by rank tier
49 
50## Installation
51 
52### Prerequisites
53- Python 3.10 or higher
54- pip package manager
55 
56### Install from Source
57 
58```bash
59# Clone the repository
60git clone https://github.com/hkaanengin/opendota-mcp-server.git
61cd opendota-mcp-server
62 
63# Create virtual environment
64python3 -m venv .venv
65source .venv/bin/activate  # On Windows: .venv\Scripts\activate
66 
67# Install with dev dependencies
68pip install -e ".[dev]"
69 
70# Or install runtime only
71pip install -e .
72```
73 
74## Usage
75 
76### Option 1: Local Server (stdio mode)
77 
78Best for Claude Desktop integration on your local machine.
79 
80#### Using Claude Desktop
81 
82**Config file location:**
83- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
84- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
85- Linux: `~/.config/Claude/claude_desktop_config.json`
86 
87**Recommended: Using the installed command**
88 
89After running `pip install -e .`, add to your `claude_desktop_config.json`:
90 
91```json
92{
93  "mcpServers": {
94    "opendota": {
95      "command": "/path/to/your/opendota-mcp-server/.venv/bin/opendota-mcp"
96    }
97  }
98}
99```
100 
101> **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.
102 
103**Alternative: Using Python module directly**
104 
105```json
106{
107  "mcpServers": {
108    "opendota": {
109      "command": "/path/to/your/opendota-mcp-server/.venv/bin/python",
110      "args": ["-m", "opendota_mcp.server"]
111    }
112  }
113}
114```
115 
116**Alternative: Using the shell script**
117 
118```json
119{
120  "mcpServers": {
121    "opendota": {
122      "command": "/path/to/your/opendota-mcp-server/start_mcp.sh"
123    }
124  }
125}
126```
127 
128**Using Docker:**
129 
130```json
131{
132  "mcpServers": {
133    "opendota": {
134      "command": "docker",
135      "args": [
136        "run",
137        "-i",
138        "--rm",
139        "-e", "MCP_TRANSPORT=stdio",
140        "hkaanengin/opendota-mcp-server:latest"
141      ]
142    }
143  }
144}
145```
146 
147After updating the config:
1481. Save the file
1492. Restart Claude Desktop completely
1503. Start a new conversation
1514. Your OpenDota tools should now be available!
152 
153#### Manual Testing
154 
155```bash
156# Run the server directly
157opendota-mcp
158 
159# Or using Python module
160python -m opendota_mcp.server
161 
162# Or using the shell script
163./start_mcp.sh
164```
165 
166### Option 2: Remote Server (HTTP mode)
167 
168Access a deployed server from anywhere.
169 
170#### Public Server
171 
172Use the publicly deployed server at:
173```
174https://opendota-mcp-server-jylza6gata-ew.a.run.app/mcp
175```
176 
177#### Claude Desktop (Remote Connection)
178 
179Add to your `claude_desktop_config.json`:
180 
181```json
182{
183  "mcpServers": {
184    "opendota": {
185      "command": "npx",
186      "args": [
187        "-y",
188        "@modelcontextprotocol/server-remote-http",
189        "https://opendota-mcp-server-jylza6gata-ew.a.run.app/mcp"
190      ]
191    }
192  }
193}
194```
195 
196#### Claude.ai Web Interface
197 
1981. Go to Claude.ai → Settings → MCP Servers
1992. Click "Add Server"
2003. Enter Server URL: `https://opendota-mcp-server-jylza6gata-ew.a.run.app/mcp`
2014. Save and start chatting!
202 
203### Option 3: Deploy Your Own
204 
205Deploy to Google Cloud Run or any container platform:
206 
207```bash
208# Build Docker image
209docker build -t opendota-mcp-server .
210 
211# Run in HTTP mode
212docker run -p 8080:8080 \
213  -e MCP_TRANSPORT=http \
214  -e PORT=8080 \
215  opendota-mcp-server
216```
217 
218## Configuration
219 
220### Environment Variables
221 
222Create a `.env` file in the project root (or copy from `.env.example`):
223 
224```env
225# OpenDota API Key (optional)
226# Get your API key from: https://www.opendota.com/api-keys
227OPENDOTA_API_KEY=
228 
229# Logging level (DEBUG, INFO, WARNING, ERROR)
230LOG_LEVEL=INFO
231 
232# Transport mode (stdio or http)
233MCP_TRANSPORT=stdio
234 
235# HTTP server port (for HTTP mode)
236PORT=8080
237```
238 
239### OpenDota API Key (Optional)
240 
241An API key is **optional** but recommended for higher rate limits and better performance.
242 
243**Rate Limits:**
244- **Without API key**: 60 requests/minute (anonymous)
245- **With API key**: Higher limits for registered users
246 
247**How to get an API key:**
248 
2491. Visit [https://www.opendota.com/api-keys](https://www.opendota.com/api-keys)
2502. Sign in with your Steam account
2513. Click "Create API Key"
2524. Copy the generated API key
2535. Add it to your `.env` file:
254   ```env
255   OPENDOTA_API_KEY=your-api-key-here
256   ```
2576. Restart the server
258 
259The server will automatically detect and use the API key when configured. You'll see a confirmation message in the logs:
260```
261✅ OpenDota API key configured (higher rate limits enabled)
262```
263 
264## Contributing
265 
266Contributions are welcome! Please:
267 
2681. Fork the repository
2692. Create a feature branch (`git checkout -b feature/amazing-feature`)
2703. Commit your changes (`git commit -m 'Add amazing feature'`)
2714. Push to the branch (`git push origin feature/amazing-feature`)
2725. Open a Pull Request
273 
274## Acknowledgments
275 
276- [OpenDota](https://www.opendota.com/) for providing the excellent Dota 2 API
277- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework
278- The Model Context Protocol team at Anthropic
279- The Dota 2 community
280 
281## Support
282 
283For issues, questions, or contributions:
284- Open an issue on [GitHub](https://github.com/hkaanengin/opendota-mcp-server/issues)
285- Check existing issues for solutions
286- Review the [OpenDota API documentation](https://docs.opendota.com)
287 
288---
289 
290**Made with ❤️ for the Dota 2 community**
291