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