faceit-mcp

A standalone MCP 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).

Requirements

• Python 3.12+
• FACEIT Data API key (free)

Setup

1. Clone and install deps

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:

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

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