JinDaGe - mcp-stockfish MCP Details

article

README

🚀 mcp-stockfish 🐟

这是一个用于链接人工智能与国际象棋引擎Stockfish的桥梁。借助Model Context Protocol（MCP）协议，它让你的AI能够与强大的Stockfish进行“对话”，让国际象棋分析变得更加便捷。

Claude Desktop with mcp-stockfish

🧠⚡🖥️ 大语言模型思考，Stockfish计算，你只需假装理解那长达15步的战术序列。

🚀 快速开始

📦 安装指南

git clone https://github.com/sonirico/mcp-stockfish
cd mcp-stockfish
make install

💻 使用示例

基础用法

# 默认模式 (标准输入输出，老派风格)
mcp-stockfish

高级用法

# 指定Stockfish路径
MCP_STOCKFISH_PATH=/your/special/stockfish mcp-stockfish

# HTTP模式 (适用于Web场景)
MCP_STOCKFISH_SERVER_MODE=http mcp-stockfish

✨ 主要特性

🔄 并发会话：可同时运行多个Stockfish实例，而不会让你的CPU不堪重负。
⚡ 完整UCI支持：提供所需的所有命令，无多余干扰。
🎯 稳定运行：具备完善的错误处理机制，与你上次失败的副业项目不同。
📊 JSON数据格式：所有数据以JSON格式传输，符合现代开发趋势。
🐳 Docker支持：支持容器化部署，避免本地环境配置的烦恼。

📚 详细文档

支持的UCI命令 ♟️

| 命令 | 描述 | | ------------------ | ------------------------------------------------------------------------ | | uci | 以UCI模式初始化引擎 | | isready | 检查引擎是否就绪，就绪则返回 readyok | | position startpos | 将棋盘设置为起始位置 | | position fen [FEN] | 使用FEN符号设置棋盘位置 | | go | 启动引擎计算最佳走法 | | go depth [n] | 搜索 n 层深度，例如：go depth 10 | | go movetime [ms] | 在指定的毫秒数内思考，例如：go movetime 1000 | | stop | 停止当前搜索 | | quit | 关闭会话 |

配置 ⚙️

环境变量

| 属性 | 详情 | |------|------| | 服务器模式 | MCP_STOCKFISH_SERVER_MODE：可选值为 "stdio" 或 "http"（默认："stdio"） | | HTTP主机 | MCP_STOCKFISH_HTTP_HOST：HTTP主机地址（默认："localhost"） | | HTTP端口 | MCP_STOCKFISH_HTTP_PORT：HTTP端口号（默认：8080） | | Stockfish路径 | MCP_STOCKFISH_PATH：Stockfish二进制文件的路径（默认："stockfish"） | | 最大并发会话数 | MCP_STOCKFISH_MAX_SESSIONS：最大并发会话数（默认：10） | | 会话超时时间 | MCP_STOCKFISH_SESSION_TIMEOUT：会话超时时间（默认："30m"） | | 命令超时时间 | MCP_STOCKFISH_COMMAND_TIMEOUT：命令超时时间（默认："30s"） | | 日志级别 | MCP_STOCKFISH_LOG_LEVEL：可选值为 debug、info、warn、error、fatal | | 日志格式 | MCP_STOCKFISH_LOG_FORMAT：可选值为 json、console | | 日志输出 | MCP_STOCKFISH_LOG_OUTPUT：可选值为 stdout、stderr |

工具参数

command：要执行的UCI命令
session_id：会话ID（可选，若未提供则自动生成）

响应格式

{
  "status": "success|error", 
  "session_id": "some-uuid",
  "command": "what you asked for",
  "response": ["what stockfish said"],
  "error": "what went wrong (if anything)"
}

会话管理

会话具备以下功能：

根据需求启动Stockfish进程。
在命令之间保持UCI状态。
在会话结束或超时时自动清理资源。
实施限制，防止资源耗尽。

集成

Claude Desktop

{
  "mcpServers": {
    "chess": {
      "command": "mcp-stockfish",
      "env": {
        "MCP_STOCKFISH_LOG_LEVEL": "info"
      }
    }
  }
}

开发

make deps     # 获取依赖
make build    # 构建项目
make test     # 运行测试（若有）
make fmt      # 格式化代码

🔧 技术细节

本项目基于 mark3labs/mcp-go 构建，借助其实现了MCP协议的处理，避免了重复造轮子。

📄 许可证

本项目采用MIT许可证，你可以自由使用，但出现问题时请不要责怪作者。

🐟 鸣谢

本项目由 Stockfish 提供支持，这是一个比我们所有人都强大的国际象棋引擎。感谢以下团队和项目：

Stockfish团队开发了优秀的国际象棋引擎。
MCP SDK for Go 处理协议，让开发更轻松。
还有咖啡，给予开发者灵感。

mcp-stockfish