Chess4LLM MCP：Stockfish MCP服务器

](https://github.com/r-baruah/Chess4LLm-MCP/stargazers)

一种用于Stockfish国际象棋引擎的高性能模型上下文协议（MCP）服务器

*生产就绪•智能缓存•丰富分析•易于集成*

特性 • 快速开始 • 文档 • 工具 • 演出

______________________________________________________________________

📋 概述

Stockfish MCP服务器连接世界级 Stockfish象棋引擎通过模型上下文协议与AI助手进行交互。它专为学习和生产使用而构建，提供了强大的国际象棋分析功能，并实现了企业级性能优化。

是什么让这个特别？

⚡ 高性能：智能位置缓存在重复查询时可提高10-100倍的速度
🎯 丰富的分析：详细评估，包括分数、主要变量和多行分析
🛠️ 生产就绪：优化发动机配置，全面的错误处理
📊 增强的用户体验：分类移动、格式化输出、视觉指示器
🔄 100%兼容：零破坏性更改，向后兼容所有MCP客户端
📚 证据充分的：广泛的指南、示例和架构文档

______________________________________________________________________

✨ 特性

核心能力

特性	描述
最佳移动计算	在可配置的搜索深度（1-20）下找到最佳移动
岗位评估	获取详细的厘泊分数和mate-in-N评估
多线分析	通过比较分析前3-5个备选方案
移动验证	核实任何职位的移动合法性
法律行动	按类型（检查、捕获、常规）分类列出所有合法行动
缓存管理	按需清除缓存以优化内存

性能特点

智能高速缓存：基于MD5的位置缓存，带有LRU驱逐功能（默认128个位置）
引擎优化：预配置哈希表（128MB）和多线程（2核）
快速查找：缓存位置在约1ms内返回，而发动机计算为400ms
内存效率高：具有可配置大小限制的智能缓存管理

开发者体验

类型安全：在整个代码库中提供全面的类型提示
证据充分的：详细的文档字符串和内联注释
错误处理：带有明确错误消息的特定异常
调试友好：在适当的级别进行广泛的记录
易于集成：基于stdio的简单通信

______________________________________________________________________

🚀 快速开始

先决条件

需求	版本	安装
Python	3.10+	下载
诗歌	最新	`pip install poetry`
Stockfish	14+	请参阅下面的平台说明

安装

1.️⃣ 安装Stockfish

macOS

brew install stockfish

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install stockfish

Windows

下载自 Stockfish下载
提取到 C:\Program Files\Stockfish\
添加到PATH或设置 STOCKFISH_PATH 环境变量

看 WINDOWS_SETUP.md 详细说明。

2.️⃣ 再进行

cd stockfish-mcp-server
poetry install

3.️⃣ 验证安装

poetry run stockfish-mcp
# Should show: "Stockfish engine initialized successfully"
# Press Ctrl+C to stop

______________________________________________________________________

🔧 整合

克劳德桌面

添加到您的Claude Desktop配置中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json\ 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stockfish": {
      "command": "poetry",
      "args": ["run", "stockfish-mcp"],
      "cwd": "/absolute/path/to/stockfish-mcp-server"
    }
  }
}

💡 小贴士：使用 pwd （macOS/Linux）或 cd （Windows）获取绝对路径。

MCP检查员

用于测试和调试：

# Install globally (one time)
npm install -g @modelcontextprotocol/inspector

# Launch inspector
npx @modelcontextprotocol/inspector poetry run stockfish-mcp

打开浏览器 http://localhost:5173 以交互方式测试工具。

自定义集成

from stockfish_mcp.server import create_server

# Create server instance
server = create_server()

# Use with your MCP client
# See ARCHITECTURE.md for details

______________________________________________________________________

🛠️ 可用工具

1. `get_best_move`

计算任何国际象棋位置的最佳移动。

参数：

{
  "fen": "string (required) - Position in FEN notation",
  "depth": "integer (optional, 1-20, default: 15) - Search depth"
}

请求示例：

{
  "fen": "rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1",
  "depth": 15
}

答复：

Best move: e2e4

特征：

可配置的搜索深度（1-20层）
自动位置缓存
快速查找重复位置

______________________________________________________________________

2. `evaluate_position`

通过评分获得全面的职位评估。

参数：

{
  "fen": "string (required) - Position in FEN notation",
  "depth": "integer (optional, 1-20, default: 15) - Search depth"
}

示例响应：

📊 Position Evaluation (depth 15):
   Score: +0.25
   Best move: e2e4
   Principal variation: e2e4 e7e5 Ng1f3 Nb8c6 Bf1c4

评估类型：

Centipawn分数: +0.25 （白色优势）， -1.50 （黑色优势）
伴侣得分: Mate in 3 （3步内强制检查）
主要变化：最佳延续线

______________________________________________________________________

3. `get_multiple_lines`

分析多个最佳移动方案。

参数：

{
  "fen": "string (required) - Position in FEN notation",
  "depth": "integer (optional, 1-20, default: 15) - Search depth",
  "num_lines": "integer (optional, 1-5, default: 3) - Number of alternatives"
}

示例响应：

🎯 Top 3 Move Alternatives:
   1. e2e4 (+0.25) → e7e5 Ng1f3 Nb8c6
   2. d2d4 (+0.18) → d7d5 c2c4 e7e6
   3. Ng1f3 (+0.15) → Ng8f6 c2c4 e7e6

使用案例：

开业准备
寻找替代方案
培训和分析
比较战略选择

______________________________________________________________________

4. `validate_move`

检查在给定位置的移动是否合法。

参数：

{
  "fen": "string (required) - Position in FEN notation",
  "move": "string (required) - Move in UCI format (e.g., 'e2e4')"
}

示例响应：

Move e2e4 is legal in the given position

______________________________________________________________________

5. `get_legal_moves`

按战术分类列出所有法律行动。

参数：

{
  "fen": "string (required) - Position in FEN notation"
}

示例响应：

♟️ Legal Moves (20 total):
   ✓ Checks (2): Bf1b5, Qd1h5
   ✗ Captures (0): 
   • Regular (18): a2a3, a2a4, b2b3, b2b4, c2c3, c2c4, d2d3, d2d4, ...

类别：

✓ 支票：给出检查的移动
✗ 捕获：移动以捕获碎片
• 常规：正常移动

______________________________________________________________________

6. `clear_cache`

清除位置缓存以释放内存。

参数： 无

示例响应：

✓ Position cache cleared successfully. Memory freed for new analysis.

何时使用：

在分析了许多职位之后
切换到其他游戏
内存优化
无缓存影响的新鲜分析

______________________________________________________________________

📊 演出

基准测试

操作	首次调用	缓存	改进
get_best_move （深度15）	380毫秒	1毫秒	快380倍 ⚡
评估_位置（深度15）	400ms	1ms	快400倍 ⚡
get_multiple_lines （3行）	1200ms	N/A	新功能🎯
get_legal_moves	8ms	不适用	增强用户体验📊

高速缓存性能

缓存命中率：典型使用时为40-60%
内存使用：128个缓存位置约1-2MB
整体提速：在真实场景中速度提高2-3倍

优化详细信息

Engine Configuration:
├─ Hash Table: 128MB (reduces redundant calculations by ~30%)
├─ Threads: 2 (improves search speed by ~40-70%)
└─ Combined: 2-3x overall performance improvement

______________________________________________________________________

📁 项目结构

stockfish-mcp-server/
├── src/
│   └── stockfish_mcp/
│       ├── __init__.py          # Package initialization
│       ├── server.py            # MCP server (tool handlers)
│       └── engine.py            # Stockfish wrapper (UCI protocol)
│
├── docs/
│   ├── ARCHITECTURE.md          # Technical architecture details
│   ├── QUICKSTART.md            # Quick start guide
│   ├── WINDOWS_SETUP.md         # Windows installation guide
│   └── IMPROVEMENTS.md          # Recent enhancements
│
├── tests/                       # Test suite (pytest)
├── pyproject.toml              # Poetry dependencies & config
├── LICENSE                      # MIT License
└── README.md                   # This file

______________________________________________________________________

🏗️ 建筑

高级概述

┌─────────────────────────────────────────────────────────────┐
│                    Claude Desktop / MCP Client               │
└─────────────────────────┬───────────────────────────────────┘
                          │ JSON-RPC over stdio
                          ▼
┌─────────────────────────────────────────────────────────────┐
│              MCP Server (server.py)                          │
│  ┌─────────────────────────────────────────────────────┐   │
│  │ Tool Handlers                                        │   │
│  │  • get_best_move    • evaluate_position             │   │
│  │  • validate_move    • get_legal_moves               │   │
│  │  • get_multiple_lines • clear_cache                 │   │
│  └─────────────────────┬───────────────────────────────┘   │
│                        │                                     │
│  ┌─────────────────────▼───────────────────────────────┐   │
│  │ Engine Wrapper (engine.py)                          │   │
│  │  • UCI Protocol Handler                             │   │
│  │  • Position Caching (MD5 keys, LRU eviction)       │   │
│  │  • Performance Optimization                         │   │
│  └─────────────────────┬───────────────────────────────┘   │
└────────────────────────┼─────────────────────────────────────┘
                         │ UCI Protocol (subprocess)
                         ▼
┌─────────────────────────────────────────────────────────────┐
│              Stockfish Chess Engine Binary                   │
└─────────────────────────────────────────────────────────────┘

关键组件

MCP服务器层 (server.py)

- 实现模型上下文协议 - 定义工具模式和处理程序 - 管理请求/响应流 - 格式化输出以获得最佳用户体验

发动机包装 (engine.py)

- 管理Stockfish子流程生命周期 - 实现UCI协议通信 - 使用MD5密钥处理位置缓存 - 优化发动机配置

国际象棋逻辑 (python-chess 图书馆）

- FEN解析和验证 - 移动生成和验证 - 董事会状态管理 - UCI移动格式转换

有关详细的体系结构文档，请参阅建筑.md.

______________________________________________________________________

🔑 关键概念

FEN符号

福赛斯·爱德华兹符号 在单行中描述国际象棋的位置。

示例（起始位置）：

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

组件：

棋子位置（从第8位到第1位）
活动颜色（w/b）
铸造权（KQkq）
途中目标广场
半移动时钟
满移动号码

UCI协议

通用国际象棋界面 -国际象棋引擎的标准协议。

常用命令：

→ uci                    # Initialize engine
← uciok                  # Engine ready
→ position fen ...       # Set position
→ go depth 15           # Calculate to depth 15
← bestmove e2e4         # Engine response

移动格式

移动使用UCI符号： [from][to][promotion]

示例：

e2e4 -从e2到e4
e7e8q -典当晋升为女王
e1g1 -Kingside铸造（白色）
O-O 和 O-O-O 不支持符号（使用UCI）

______________________________________________________________________

🧪 发展

运行测试

# Run all tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=stockfish_mcp

# Run specific test
poetry run pytest tests/test_engine.py

代码质量

# Format code
poetry run black src/

# Sort imports
poetry run isort src/

# Type checking (if mypy installed)
poetry run mypy src/

调试模式

通过设置环境变量启用详细日志记录：

export LOG_LEVEL=DEBUG
poetry run stockfish-mcp

或修改 server.py:

logging.basicConfig(level=logging.DEBUG)

______________________________________________________________________

🎓 学习路径

该项目为以下方面提供教育资源：

1. MCP协议实现

工具定义和模式设计
请求/响应处理
错误管理
基于标准的沟通

2. 象棋引擎集成

UCI协议通信
子流程管理
位置分析技术
移动生成和验证

3. 性能优化

缓存策略（LRU、MD5密钥）
发动机配置调整
内存管理
基准驱动优化

4. 生产最佳实践

带提示的类型安全
全面的错误处理
日志记录和调试
文件标准

学习资源：

建筑.md -深入实施
QUICKSTART.md -分步教程
改进.md -解释最近的增强功能

______________________________________________________________________

📈 路线图

当前版本：0.2.0✅

✅ 核心MCP服务器实现
✅ 位置缓存系统
✅ 多线分析
✅ 增强的输出格式
✅ 性能优化

计划的功能

v0.3.0

\[\]持久缓存（磁盘存储）
\[\]基于时间的分析（除深度外）
\[\]PGN游戏导入/导出
\[\]位置历史跟踪

v0.4.0

\[\]开本书集成
\[\]桌面支持（残局数据库）
\[\]游戏注释生成
\[\]带谜题的训练模式

v1.0.0

\[\]HTTP/SSE传输支持
\[\]多引擎支持（Leela等）
\[\]用于测试的Web UI
\[\]生产部署指南

______________________________________________________________________

🤝 贡献

欢迎投稿！以下是如何提供帮助：

报告问题

检查现有问题
提供最小的复制案例
包括系统信息
附上相关日志

拉取请求

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
通过测试进行更改
格式代码： poetry run black . && poetry run isort .
承诺： git commit -m 'Add amazing feature'
推： git push origin feature/amazing-feature
打开拉取请求

开发设置

# Clone repository
git clone https://github.com/yourusername/stockfish-mcp-server.git
cd stockfish-mcp-server

# Install dependencies including dev tools
poetry install --with dev

# Install pre-commit hooks (optional)
pre-commit install

# Run tests
poetry run pytest

______________________________________________________________________

🐛 故障排除

常见问题

❌ "Stockfish binary not found"

解决：

为您的平台安装Stockfish（请参阅安装部分）
集 STOCKFISH_PATH 环境变量：

   export STOCKFISH_PATH="/path/to/stockfish"

将Stockfish添加到系统PATH

验证安装：

stockfish
# Should start Stockfish with version info

❌ "Module not found" errors

解决方案：

# Reinstall dependencies
poetry install --no-cache

# Or force rebuild
poetry env remove python
poetry install

❌ Claude Desktop not detecting server

检查表：

✅ 配置文件路径正确
✅ JSON语法有效
✅ 使用的绝对路径（非相对路径）
✅ 诗在路上
✅ 克劳德桌面已重新启动

检查日志：

macOS： ~/Library/Logs/Claude/
窗户： %APPDATA%\Claude\logs\

❌ Slow performance

优化：

增加缓存大小 engine.py:

   engine = StockfishEngine(cache_size=256)

减少搜索深度以获得更快的结果
查看Stockfish版本（推荐14+）
验证CPU是否受到限制

❌ Memory issues

解决：

使用定期清除缓存 clear_cache 工具
减小缓存大小：

   engine = StockfishEngine(cache_size=64)

降低Stockfish哈希表的大小 _configure_engine()

______________________________________________________________________

📚 其他资源

文档

MCP规范 -MCP协议官方文件
MCP Python SDK -Python实现
Stockfish维基 -发动机文档
UCI协议 -通用国际象棋界面指南
Python象棋 -图书馆文件

社区

MCP故障 -社区支持
Stockfish Discord -发动机讨论
国际象棋编程维基 -深厚的技术知识

______________________________________________________________________

📄 许可证

该项目根据 MIT许可证 -看看许可证文件以获取详细信息。

太长，读不下去了

✅ 允许商业用途
✅ 允许修改
✅ 允许分发
✅ 允许私人使用
❌ 无责任
❌ 无担保

______________________________________________________________________

🙏 致谢

构建于

模型上下文协议 -协议规范和SDK
长筒鱼 -世界上最强的国际象棋引擎
Python象棋 -Niklas Fiekas的国际象棋图书馆
诗歌 -依赖关系管理

灵感

切斯帕mcp发动机威尔逊Urdaneta
Stockfish开发团队
MCP社区

特别感谢

Claude AI用于测试和反馈
国际象棋编程社区
开源贡献者

______________________________________________________________________

📞 支持

获取帮助

文档：检查 QUICKSTART.md 和建筑.md
问题：搜索或创建问题
讨论：加入讨论
MCP社区: Discord服务器

发现Bug了吗？

请举报！包括：

操作系统和版本
Python版本(python --version)
Stockfish版本(stockfish 输出）
错误消息和日志
重现步骤

______________________________________________________________________

由以下材料制成♟️ 由社区

⭐ GitHub上的明星🐛 报告Bug•💡 请求功能

Chess4 L Lm MCP

快速接入

详细介绍

Chess4LLM MCP：Stockfish MCP服务器

📋 概述

是什么让这个特别？

✨ 特性

核心能力

性能特点

开发者体验

🚀 快速开始

先决条件

安装

1.️⃣ 安装Stockfish

2.️⃣ 再进行

3.️⃣ 验证安装

🔧 整合

克劳德桌面

MCP检查员

自定义集成

🛠️ 可用工具

1. get_best_move

2. evaluate_position

3. get_multiple_lines

4. validate_move

5. get_legal_moves

6. clear_cache

📊 演出

基准测试

高速缓存性能

优化详细信息

📁 项目结构

🏗️ 建筑

高级概述

关键组件

🔑 关键概念

FEN符号

UCI协议

移动格式

🧪 发展

运行测试

代码质量

调试模式

🎓 学习路径

1. MCP协议实现

2. 象棋引擎集成

3. 性能优化

4. 生产最佳实践

📈 路线图

当前版本：0.2.0✅

计划的功能

v0.3.0

v0.4.0

v1.0.0

🤝 贡献

报告问题

拉取请求

开发设置

🐛 故障排除

常见问题

📚 其他资源

文档

相关项目

社区

📄 许可证

🙏 致谢

构建于

灵感

特别感谢

📞 支持

获取帮助

发现Bug了吗？

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `get_best_move`

2. `evaluate_position`

3. `get_multiple_lines`

4. `validate_move`

5. `get_legal_moves`

6. `clear_cache`