内容
# 国际象棋MCP服务器
MCP服务器，暴露国际象棋分析工具（Stockfish + [Maia2](https://github.com/CSSLab/maia2)人类移动预测），可与Claude Desktop、Claude Code或任何MCP兼容客户端一起使用。
## 先决条件
- Python 3.10+
- [Stockfish](https://stockfishchess.org/download/)二进制文件
- 推荐使用CUDA GPU（CPU可以使用，但Maia2推理会较慢）
## 快速开始
```bash
git clone https://github.com/CSSLab/chess-mcp.git
cd chess-mcp
pip install -r requirements.txt
```
安装Stockfish：
```bash
# macOS
brew install stockfish
# Ubuntu / Debian
sudo apt install stockfish
# Windows — 从 https://stockfishchess.org/download/ 下载
```
然后设置`STOCKFISH_PATH`环境变量为二进制文件位置：
```bash
# macOS (Homebrew)
export STOCKFISH_PATH=$(which stockfish)
# 或直接指定路径
export STOCKFISH_PATH=/usr/local/bin/stockfish
```
## 配置
服务器通过环境变量进行配置：
| 变量 | 描述 | 默认值 |
|---|---|---|
| `STOCKFISH_PATH` | Stockfish二进制文件路径 | **必填** |
| `STOCKFISH_DEPTH` | Stockfish搜索深度 | `24` |
| `STOCKFISH_TOP_N` | 默认的Stockfish移动顶部数量 | `3` |
| `MAIA2_TYPE` | 模型类型：`rapid`或`blitz` | `rapid` |
| `MAIA2_DEVICE` | PyTorch设备：`cuda`或`cpu` | `cuda` |
| `MAIA2_TOP_N` | 默认的Maia2预测顶部数量 | `5` |
| `MAIA2_SAVE_ROOT` | 自动下载的模型权重目录 | `./models` |
模型权重在首次运行时通过`maia2.model.from_pretrained()`自动下载。
## 与Claude一起使用
复制`claude_mcp_config.example.json`并编辑路径以适应您的设置。
**Claude Desktop** — 将服务器条目添加到您的Claude Desktop MCP配置文件中（macOS上的`~/Library/Application Support/Claude/claude_desktop_config.json`）。
**Claude Code** — 添加到您的项目或用户设置中：
```bash
claude mcp add chess-tools -- python /path/to/chess-mcp/server.py
```
或将示例JSON中的配置添加到`.claude/settings.json`。
## 可用工具
### 棋盘和移动
- **is_move_legal** — 检查移动是否合法
- **get_legal_moves** — 列出所有合法移动，按棋子分组
- **make_move** / **make_moves** — 应用移动并返回生成的FEN
### 符号表示法
- **uci_to_san** / **uci_to_san_batch** — 将UCI转换为SAN
- **san_to_uci** / **san_to_uci_batch** — 将SAN转换为UCI
### PGN和FEN
- **pgn_to_fen** — 获取PGN游戏中的FEN
- **get_pgn_moves** — 从原始PGN中提取干净的移动列表
### 棋盘检查
- **get_piece_at** — 确定方格上的棋子
- **get_game_status** — 回合、将军、王车易位、和局条件
- **board_to_ascii** / **board_to_svg** — 渲染棋盘图
### 分析
- **evaluate_position** — 静态评估（物质、兵、机动性）
- **find_tactics** — 钉、叉、将军、悬空子
- **stockfish_analyse** — Stockfish引擎分析与胜负
### 人类移动预测（Maia2）
- **predict_human_move** — 预测给定Elo的玩家会走的移动
- **predict_human_move_all_levels** — 比较所有技能水平（1050–2050）的预测
