Faceit Mcp
About
Standalone MCP server for live CS2 FACEIT data — player stats, match history, comparisons, leaderboard, and ELO trend. Works with Claude Desktop and Claude Code.
Details
- Author
- bluemadisonblue
- Downloads
- 296
- Categories
- Other
Jump to
- Get player ELO, level, K/D, HS%, win rate, and streaks
- View match history with map, score, K/D, kills, and HS%
- Compare up to 6 players side-by-side
- Analyze recent form with per-map breakdown
- Retrieve full match scoreboards with all player stats
- Show per-map win rate, K/D, HS%, and K/R
- Live ELO leaderboard and trend (requires SQLite DB)
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Faceit McpCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Clone the repository, install dependencies with pip install -r requirements.txt, and set your FACEIT API key in a .env file. Then configure the server in claude_desktop_config.json or add it via claude mcp add for Claude Code.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"faceit mcp": {
"faceit-cs2": {
"command": "python",
"args": [
"C:/full/path/to/faceit-mcp/faceit_mcp_server.py"
],
"env": {
"FACEIT_API_KEY": "your_key_here"
}
}
}
}
}McpServers
{
"faceit-cs2": {
"command": "python",
"args": [
"C:/full/path/to/faceit-mcp/faceit_mcp_server.py"
],
"env": {
"FACEIT_API_KEY": "your_key_here"
}
}
}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
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
