# hltv-csgo-mcp

[![npm version](https://img.shields.io/npm/v/hltv-csgo-mcp)](https://www.npmjs.com/package/hltv-csgo-mcp)
[![GitHub](https://img.shields.io/badge/GitHub-Mooooooon%2Fhltv--csgo--mcp-blue)](https://github.com/Mooooooon/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:

```powershell
$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](https://github.com/lwthiker/curl-impersonate), which mimics Chrome's TLS handshake.

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

```powershell
# 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:

```powershell
npm install
npm run build
node dist/cli.js
```

After the package is published to npm:

```powershell
npx -y hltv-csgo-mcp
```

Logs use stderr so stdout remains a valid MCP transport.

## Codex setup

Add the package with:

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

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

```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

```json
{
  "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

```powershell
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:

```powershell
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](https://www.hltv.org/) before deploying or modifying request behavior.