Faceit Mcp
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_leaderboardandget_elo_trendwork 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
Server Config
{
"mcpServers": {
"faceit-cs2": {
"command": "python",
"args": [
"C:/full/path/to/faceit-mcp/faceit_mcp_server.py"
],
"env": {
"FACEIT_API_KEY": "your_key_here"
}
}
}
}