# faceit-mcp

A standalone [MCP](https://modelcontextprotocol.io/) server that gives Claude live **CS2 FACEIT** data — player stats, match history, side-by-side comparisons, leaderboard, and ELO trend.

Works with **Claude Desktop** and **Claude Code**. Single-file, no framework dependencies beyond `mcp`, `aiohttp`, `aiosqlite`, and `python-dotenv`.

## Demo

> **You:** Compare zywoo, NiKo, and sh1ro side by side

> **Claude:** Here's a side-by-side comparison of the three players:
>
> | | ZywOo | NiKo | sh1ro |
> |---|---|---|---|
> | **ELO** | 4521 | 4218 | 4384 |
> | **Level** | 10 | 10 | 10 |
> | **K/D** | 1.43 | 1.38 | 1.41 |
> | **HS%** | 52.1% | 48.7% | 44.2% |
> | **Win Rate** | 61.3% | 58.9% | 60.1% |
> | **Avg Kills** | 24.8 | 23.6 | 23.1 |
> | **K/R** | 0.91 | 0.87 | 0.89 |

---

> **You:** How has NiKo been playing in his last 20 matches?

> **Claude:** NiKo's recent form over 20 matches:
> - **Record:** 13W – 7L (65.0% win rate)
> - **Avg K/D:** 1.42 | **Avg kills:** 24.3 | **Avg HS%:** 49.1%
> - **Current streak:** 3W
>
> Best maps: de_inferno (8W-2L, 70% wr), de_ancient (4W-1L, 80% wr)
> Worst map: de_vertigo (1W-3L, 25% wr)

## Tools

| Tool | Description |
|------|-------------|
| `get_player_stats` | ELO, skill level, region, lifetime K/D, HS%, win rate, streaks |
| `get_match_history` | Last N matches — map, W/L, K/D, kills, HS%, K/R |
| `compare_players` | Side-by-side stats for 2–6 FACEIT nicknames |
| `get_recent_form` | Aggregated stats from last N matches: win rate, avg K/D, current streak, per-map breakdown |
| `get_match_details` | Full scoreboard for a match by ID — teams, score, all player stats, multi-kills |
| `get_player_map_stats` | Per-map win rate, K/D, HS%, and K/R from lifetime segments |
| `get_leaderboard` | Registered users ranked by live ELO |
| `get_elo_trend` | Stored ELO snapshots for a registered user |

> All tools except `get_leaderboard` and `get_elo_trend` work for **any** public FACEIT player with just an API key. The leaderboard and ELO trend tools require a SQLite DB with registered users (see [DB setup](#leaderboard--elo-trend)).

## Requirements

- Python 3.12+
- [FACEIT Data API key](https://developers.faceit.com/) (free)

## Setup

**1. Clone and install deps**

```bash
git clone https://github.com/bluemadisonblue/faceit-mcp.git
cd faceit-mcp
pip install -r requirements.txt
```

**2. Set your API key**

Create a `.env` file next to the script:

```
FACEIT_API_KEY=your_key_here
```

Or pass it as an environment variable directly in the config below.

## Connect to Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "faceit-cs2": {
      "command": "python",
      "args": ["C:/full/path/to/faceit-mcp/faceit_mcp_server.py"],
      "env": { "FACEIT_API_KEY": "your_key_here" }
    }
  }
}
```

Config file location:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

## Connect to Claude Code

```bash
claude mcp add faceit-cs2 -- python /full/path/to/faceit-mcp/faceit_mcp_server.py
```

Then set `FACEIT_API_KEY` in the `.env` file next to the script.

## Example prompts

Once connected, just ask Claude naturally:

- *"What are s1mple's lifetime stats?"*
- *"Show me the last 10 matches for NiKo"*
- *"Compare zywoo, device, and sh1ro side by side"*
- *"How has NiKo been performing over his last 20 matches?"*
- *"Show the full scoreboard for match 1-abc123…"*
- *"Which maps does sh1ro perform best on?"*
- *"Show the leaderboard for our group"*
- *"How has my ELO changed over the last month?"*

## Leaderboard & ELO trend

`get_leaderboard` and `get_elo_trend` read from a local SQLite database. By default the DB lives at `~/.faceit-mcp/data.db` and is created automatically on startup.

To populate it, point `DB_PATH` at a database that has a `users` table:

```
DB_PATH=/path/to/your/bot_data.db
```

If you use the companion [CS2 FACEIT Telegram bot](https://github.com/bluemadisonblue/CS2DATA), set `DB_PATH` to the bot's database and these tools will reflect your registered users automatically.

## Environment variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `FACEIT_API_KEY` | Yes | — | FACEIT Data API v4 key |
| `DB_PATH` | No | `~/.faceit-mcp/data.db` | SQLite database path |
| `FACEIT_CIRCUIT_FAILURE_THRESHOLD` | No | `4` | Consecutive failures before circuit opens (`0` to disable) |
| `FACEIT_CIRCUIT_OPEN_SEC` | No | `60` | How long the circuit stays open (seconds) |

## License

MIT