# Faceit Mcp

> MCP server for Claude — live CS2 FACEIT stats, match history, player comparisons, and ELO tracking

- **Type:** MCP server
- **Install:** `agentstack add mcp-tqakdev-faceit-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tqakdev](https://agentstack.voostack.com/s/tqakdev)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tqakdev](https://github.com/tqakdev)
- **Source:** https://github.com/tqakdev/faceit-mcp
- **Website:** https://github.com/bluemadisonblue/faceit-mcp

## Install

```sh
agentstack add mcp-tqakdev-faceit-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [tqakdev](https://github.com/tqakdev)
- **Source:** [tqakdev/faceit-mcp](https://github.com/tqakdev/faceit-mcp)
- **License:** MIT
- **Homepage:** https://github.com/bluemadisonblue/faceit-mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** yes
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tqakdev-faceit-mcp
- Seller: https://agentstack.voostack.com/s/tqakdev
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.