liquipedia-dota2-mcp

Read-only MCP server and Codex skill for sourced Dota 2 tournament, team, player, schedule, and result data from Liquipedia.

This is an unofficial community project. It is not affiliated with or endorsed by Liquipedia, Team Liquid, Valve, or OpenAI.

Features

• Five structured MCP tools for entity search, tournament, team, player, and match queries.
• Revision-level source metadata, coverage indicators, and explicit parse warnings.
• Persistent SQLite cache, duplicate-request coalescing, and Liquipedia-compliant request queues.
• Local stdio transport for Codex, ChatGPT desktop, Claude Desktop, and other MCP clients.
• Bundled liquipedia-dota2 Skill under skills/liquipedia-dota2.

Requirements

• Node.js 22 or newer. The server uses Node's built-in SQLite module and does not require a native dependency build.
• A custom LIQUIPEDIA_USER_AGENT containing a project name, version, and contact URL or email.

Example:

MyDotaAssistant/1.0 (developer@example.com)

The server refuses to start without a valid identifying User-Agent. It only sends automated requests to https://liquipedia.net/dota2/api.php; it does not scrape rendered website pages.

Install and run

After the package is published to npm:

$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npx -y liquipedia-dota2-mcp

Directly from GitHub, without npm publishing:

$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npx -y github:Mooooooon/liquipedia-dota2-mcp

On npm 12 and newer, git package installs are disabled by default, so add --allow-git=root:

$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npx -y --allow-git=root github:Mooooooon/liquipedia-dota2-mcp

dist/ is built automatically on install (prepare on npm 11 and earlier, pack-time prepack on npm 12), so the installer needs no build step.

From a source checkout:

npm install
npm run build
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
node dist/cli.js

Logs use stderr so stdout remains a valid MCP transport.

Codex setup

Codex CLI and the ChatGPT desktop app share local MCP configuration. Add the published package with:

codex mcp add liquipedia-dota2 --env "LIQUIPEDIA_USER_AGENT=MyDotaAssistant/1.0 (developer@example.com)" -- npx -y liquipedia-dota2-mcp

Or add this to ~/.codex/config.toml:

[mcp_servers.liquipedia_dota2]
command = "npx"
args = ["-y", "liquipedia-dota2-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

[mcp_servers.liquipedia_dota2.env]
LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"

Install the bundled Skill by copying skills/liquipedia-dota2 into either the repository's .agents/skills directory or the user's .agents/skills directory. The Skill intentionally has no remote MCP dependency URL; configure the local server separately.

Claude Desktop setup

Add the server to the Claude Desktop MCP configuration:

{
  "mcpServers": {
    "liquipedia-dota2": {
      "command": "npx",
      "args": ["-y", "liquipedia-dota2-mcp"],
      "env": {
        "LIQUIPEDIA_USER_AGENT": "MyDotaAssistant/1.0 (developer@example.com)"
      }
    }
  }
}

Tools

Tool	Purpose
search_dota2_entities	Find tournament, team, and player candidates.
get_dota2_tournament	Read tournament metadata, participants, and placements.
get_dota2_team	Read team metadata, roster, and coaches.
get_dota2_player	Read player identity and team history.
list_dota2_matches	Read match schedule/result rows for a confirmed tournament or team.

Every call returns data, section-level coverage, warnings, source, and a typed error. A section marked unavailable means the current parser could not establish the data; it does not mean that the source contains no records.

Cache and limits

The server enforces minimum intervals of 2.1 seconds for ordinary MediaWiki requests and 31 seconds for action=parse. These minimums cannot be weakened through environment variables. Defaults are:

• Search: 6 hours
• Team/player: 24 hours
• Upcoming or ongoing tournament: 30 minutes
• Completed tournament: 7 days
• Match list: 15 minutes

Set LIQUIPEDIA_CACHE_PATH to choose the SQLite file. When Liquipedia is unavailable, an expired cache entry may be returned with source.is_stale: true and its stale age.

Development

npm run check
npm test
npm run build
npm pack --dry-run

Default tests are completely offline. An opt-in live smoke test performs a small number of compliant API calls:

$env:LIQUIPEDIA_LIVE_TEST = "1"
$env:LIQUIPEDIA_USER_AGENT = "MyDotaAssistant/1.0 (developer@example.com)"
npm run test:live

Data and licensing

Project code is MIT licensed. Liquipedia text/data is separately provided under CC BY-SA 3.0 and remains subject to Liquipedia's API terms. Tool results include attribution, license, source page, revision, and fetch time. Media such as logos and player photographs is not downloaded or redistributed.

See Liquipedia API terms before deploying or modifying request behavior.