hltv-csgo-mcp

Read-only MCP server and Codex skill for Counter-Strike schedules, results, teams, players, and events from HLTV.org.

This is an unofficial community project. It is not affiliated with or endorsed by HLTV.org, Valve, or OpenAI.

Features

• Three structured MCP tools for HLTV entity search, match lists, and match details.
• Upcoming, live, and finished match parsing with teams, scores, event, time, format, and stars.
• Match-page parsing with maps, map scores, and stream links.
• Persistent SQLite cache, duplicate-request coalescing, and a serialized request queue.
• Local stdio transport for Codex, ChatGPT desktop, Claude Desktop, and other MCP clients.
• Bundled hltv-csgo Skill under skills/hltv-csgo.

Requirements

• Node.js 22 or newer. The server uses Node's built-in SQLite module and does not require a native dependency build.
• A curl executable on PATH. On Windows 10/11, curl.exe is included with the operating system.

By default the server uses a browser-like User-Agent because HLTV.org serves its server-rendered pages through Cloudflare. If the server IP receives a Cloudflare challenge, set HLTV_PROXY to a cleaner egress proxy or HLTV_COOKIE to a valid cf_clearance cookie obtained from a browser on the same IP and User-Agent. You can override the User-Agent when needed:

$env:HLTV_USER_AGENT = "MyCsAssistant/1.0 (developer@example.com)"
$env:HLTV_PROXY = "http://127.0.0.1:7890"
$env:HLTV_COOKIE = "cf_clearance=...; __cf_bm=..."

The server only sends automated requests to https://www.hltv.org pages. It does not scrape logged-in or premium content.

Cloudflare and curl-impersonate

HLTV.org may challenge normal curl by TLS fingerprint rather than User-Agent. On Linux servers, the recommended fix is curl-impersonate, which mimics Chrome's TLS handshake.

# Linux
HLTV_CURL_BINARY="/usr/local/bin/curl_chrome124" node dist/cli.js

# Windows
$env:HLTV_CURL_BINARY = "C:\tools\curl-impersonate\curl_chrome124.exe"
node dist/cli.js

If HLTV_CURL_BINARY is unset, the server uses the system curl. You can also configure PATH so curl itself points to the impersonated binary, but the explicit variable is more predictable.

Install and run

From a source checkout:

npm install
npm run build
node dist/cli.js

After the package is published to npm:

npx -y hltv-csgo-mcp

Logs use stderr so stdout remains a valid MCP transport.

Codex setup

Add the package with:

codex mcp add hltv-csgo -- npx -y hltv-csgo-mcp

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

[mcp_servers.hltv_csgo]
command = "npx"
args = ["-y", "hltv-csgo-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 120

Install the bundled Skill by copying skills/hltv-csgo 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

{
  "mcpServers": {
    "hltv-csgo": {
      "command": "npx",
      "args": ["-y", "hltv-csgo-mcp"]
    }
  }
}

Tools

Tool	Purpose
search_hltv_entities	Find teams, players, and events by name.
list_hltv_matches	List upcoming, live, finished, or all matches with optional filters.
get_hltv_match	Read one match page's teams, score, event, time, maps, and streams.

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 HLTV contains no records.

Cache and limits

The server enforces a minimum interval of 2.1 seconds between HLTV requests. This minimum cannot be weakened through environment variables. Default TTLs are:

• Search: 24 hours
• Upcoming/live match list: 5 minutes
• Finished results: 15 minutes
• Match details: 15 minutes

Set HLTV_CACHE_PATH to choose the SQLite file. When HLTV 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 and use fixture HTML. Live pages can be exercised directly from Node, but do so sparingly and respect HLTV's infrastructure:

node --input-type=module -e "import { loadConfig, HltvHtmlDataSource } from './dist/index.js'; const ds = new HltvHtmlDataSource(loadConfig({ HLTV_CACHE_PATH: ':memory:' })); console.log(JSON.stringify(await ds.listMatches({ kind: 'upcoming', limit: 3 }), null, 2)); ds.close();"

Data and licensing

Project code is MIT licensed. HLTV match, team, player, and event data is displayed for reference and remains subject to HLTV.org's terms of use. Tool results include attribution, source page, and fetch time. Logos, player photos, and other media are not downloaded or redistributed.

See HLTV.org before deploying or modifying request behavior.