Faceit Mcp

faceit-mcp

一个独立的 MCP 服务，为 Claude 提供实时的 CS2 FACEIT 数据——玩家统计、比赛历史、并排对比、排行榜和 ELO 趋势。

兼容 Claude Desktop 和 Claude Code。单文件实现，除 mcp、aiohttp、aiosqlite 和 python-dotenv 外无框架依赖。

演示

你： 并排比较 zywoo、NiKo 和 sh1ro

Claude： 以下是三位玩家的并排对比：

	ZywOo	NiKo	sh1ro
ELO	4521	4218	4384
等级	10	10	10
K/D	1.43	1.38	1.41
爆头率	52.1%	48.7%	44.2%
胜率	61.3%	58.9%	60.1%
平均击杀数	24.8	23.6	23.1
K/R	0.91	0.87	0.89

---

你： NiKo 最近 20 场比赛表现如何？

Claude： NiKo 最近 20 场比赛的表现：

• 战绩： 13 胜 – 7 负（胜率 65.0%）
• 平均 K/D： 1.42 | 平均击杀数： 24.3 | 平均爆头率： 49.1%
• 当前连胜／连败： 3 连胜

最佳地图：de_inferno（8 胜 2 负，胜率 70%）、de_ancient（4 胜 1 负，胜率 80%） 最差地图：de_vertigo（1 胜 3 负，胜率 25%）

工具

工具	描述
get_player_stats	ELO、技能等级、地区、职业生涯 K/D、爆头率、胜率、连胜／连败
get_match_history	最近 N 场比赛——地图、胜／负、K/D、击杀数、爆头率、K/R
compare_players	并排比较 2–6 个 FACEIT 昵称的统计数据
get_recent_form	最近 N 场比赛的汇总统计：胜率、平均 K/D、当前连胜／连败、各地图明细
get_match_details	根据比赛 ID 获取完整记分板——队伍、比分、所有玩家数据、多重击杀
get_player_map_stats	根据职业生涯数据统计各地图的胜率、K/D、爆头率和 K/R
get_leaderboard	按实时 ELO 排名的已注册用户
get_elo_trend	已注册用户保存的 ELO 快照

除 get_leaderboard 和 get_elo_trend 外，所有工具只需 API 密钥即可用于任何公开的 FACEIT 玩家。排行榜和 ELO 趋势工具需要包含已注册用户的 SQLite 数据库（参见 数据库设置）。

要求

• Python 3.12+
• FACEIT Data API 密钥（免费）

设置

1. 克隆并安装依赖

git clone https://github.com/bluemadisonblue/faceit-mcp.git
cd faceit-mcp
pip install -r requirements.txt

2. 设置 API 密钥

在脚本旁创建一个 .env 文件：

FACEIT_API_KEY=your_key_here

也可以在下方配置中直接将其作为环境变量传入。

连接到 Claude Desktop

将以下内容添加到 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" }
    }
  }
}

配置文件位置：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

连接到 Claude Code

claude mcp add faceit-cs2 -- python /full/path/to/faceit-mcp/faceit_mcp_server.py

然后在脚本旁的 .env 文件中设置 FACEIT_API_KEY。

示例提示词

连接后，直接用自然语言询问 Claude：

• “s1mple 的职业生涯数据是什么？”
• “显示 NiKo 最近 10 场比赛”
• “并排比较 zywoo、device 和 sh1ro”
• “NiKo 最近 20 场比赛表现如何？”
• “显示比赛 1-abc123… 的完整记分板”
• “sh1ro 在哪些地图上表现最好？”
• “显示我们小组的排行榜”
• “我过去一个月的 ELO 变化如何？”

排行榜与 ELO 趋势

get_leaderboard 和 get_elo_trend 从本地 SQLite 数据库读取数据。默认情况下，数据库位于 ~/.faceit-mcp/data.db，并会在启动时自动创建。

要填充数据库，请将 DB_PATH 指向包含 users 表的数据库：

DB_PATH=/path/to/your/bot_data.db

如果你使用配套的 CS2 FACEIT Telegram bot，请将 DB_PATH 设置为该 bot 的数据库，这些工具便会自动显示已注册用户的数据。

环境变量

变量	必填	默认值	描述
FACEIT_API_KEY	是	—	FACEIT Data API v4 密钥
DB_PATH	否	~/.faceit-mcp/data.db	SQLite 数据库路径
FACEIT_CIRCUIT_FAILURE_THRESHOLD	否	4	熔断器打开前的连续失败次数（0 表示禁用）
FACEIT_CIRCUIT_OPEN_SEC	否	60	熔断器保持打开的时长（秒）

许可证

MIT