mcsm-mcp —— MCSManager Minecraft 服务器管理 MCP Server

由 AstrBot 插件 siwu-mcs-manager-1_0（源插件 AstrBot_siwu-mcs-manager）转换的独立 MCP Server： 通过 MCSManager 面板 API 管理 Minecraft 服务器实例（列表 / 状态 / 启动 / 停止 / 重启 / 强停 / 控制台指令）， 供任意支持 MCP 的客户端（Claude Desktop、IDE、agent 框架等）即插即用。

工具一览（10 个）

工具	说明
mcs_list_instances	列出所有服务器实例（名称/状态/在线玩家/端口）
mcs_instance_status	查询指定实例状态详情（状态/在线玩家/端口/启动命令）
mcs_start_instance	启动指定实例（后台异步执行）
mcs_stop_instance	正常停止指定实例（安全存档）
mcs_restart_instance	重启指定实例
mcs_kill_instance	强制停止指定实例（杀进程，可能丢数据）
mcs_exec_command	向实例发送控制台指令（say/op/whitelist/give/tp/list 等）
mcs_wait_for_status	轮询等待实例达到目标状态（替代插件的后台推送通知）
mcs_get_config	查看当前生效配置（API Key/密码已脱敏）
mcs_reload_config	热重载配置（改完 .env 无需重启），也可切换配置文件

与原插件的差异

原插件（AstrBot）	本 MCP Server
工具返回中文文本，由 LLM 组织回复	返回结构化 JSON，调用方自行组织
QQ 群权限（admin_ids / admin_role）	读写开关 MCSM_ALLOW_WRITE（默认只读），调用方客户端负责访问控制
启动/停止后后台轮询 + 主动推送通知	mcs_wait_for_status 由 LLM 按需轮询确认
mc列表 等唤醒词命令	交给客户端/LLM 直接用工具（无聊天上下文）
强制 Agent 工具钩子/系统提示注入	MCP 工具天然由客户端按需暴露，无需注入

快速开始

cd servers/mcs-manager
python -m venv .venv                 # 或 uv venv .venv
.venv/Scripts/pip install -e .        # 或 uv pip install -p .venv -e .

配置（复制 .env.example 为 .env 填写，或直接用环境变量）：

MCSM_BASE_URL=http://127.0.0.1:23333   # 面板地址
MCSM_API_KEY=xxxx                      # v10 API Key（推荐）；或 MCSM_USERNAME + MCSM_PASSWORD
MCSM_ALLOW_WRITE=1                     # 写操作开关：0=只读（默认），1=允许启动/停止等

如何修改配置（插件配置 → MCP 配置）

原 AstrBot 插件在管理面板里改配置；MCP 化后配置变成 servers/mcs-manager/.env 文件（或环境变量）， 与原插件配置项的对应关系见下表，默认值完全一致：

原插件配置项	MCP 环境变量	说明
mcs_base_url	MCSM_BASE_URL	面板地址
mcs_api_key	MCSM_API_KEY	v10 API Key（推荐）
mcs_username / mcs_password	MCSM_USERNAME / MCSM_PASSWORD	账号密码登录（v9）
mcs_api_timeout	MCSM_TIMEOUT	请求超时（秒）
mcs_permission_enabled + mcs_admin_ids/mcs_admin_role	MCSM_ALLOW_WRITE	QQ 群权限 → 读写总开关（默认只读）
mcs_command_whitelist	MCSM_COMMAND_WHITELIST	指令白名单（逗号分隔）
mcs_blocked_commands	MCSM_BLOCKED_COMMANDS	指令黑名单
mcs_operation_wait	MCSM_OPERATION_WAIT	wait 工具默认等待秒数
mcs_enabled	—（进程启动即启用）	不再需要总开关，不启动进程即关闭
mcs_force_agent_tool	—（无意义）	MCP 工具由客户端按需暴露，无需强制注入

修改步骤：

1. 编辑 servers/mcs-manager/.env（没有就先 cp .env.example .env）；
2. 调用工具 mcs_reload_config 热生效，或直接重启 Server 进程；
3. 用 mcs_get_config 核对生效值（凭据会脱敏显示为 ***）。

若通过客户端配置传环境变量（如 Claude Desktop 配置里的 env 块），改完同样调用 mcs_reload_config 或重启即可生效。

运行

stdio（本地进程，推荐）：

.venv/Scripts/python -m mcsm_mcp
# 或已安装的入口命令：mcsm-mcp

HTTP（远程/多客户端）：

.venv/Scripts/python -m mcsm_mcp --transport http --host 127.0.0.1 --port 8000
# 端点：http://127.0.0.1:8000/mcp （streamable-http）

客户端接入示例（stdio）

Claude Desktop 的 claude_desktop_config.json：

{
  "mcpServers": {
    "mcs-manager": {
      "command": "<安装路径>/.venv/Scripts/python.exe",  // Windows；Linux/macOS 用 <安装路径>/.venv/bin/python
      "args": ["-m", "mcsm_mcp"],
      "env": {
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "你的面板 API Key",
        "MCSM_ALLOW_WRITE": "1"
      }
    }
  }
}

调试：npx @modelcontextprotocol/inspector 中选择 stdio 并填上述 command/args。

完整环境变量

变量	说明	默认
MCSM_BASE_URL	面板地址（不带末尾斜杠）	http://127.0.0.1:23333
MCSM_API_KEY	面板 API Key（v10 推荐）	空
MCSM_USERNAME / MCSM_PASSWORD	账号密码登录（v9 或未配 Key）	空
MCSM_TIMEOUT	面板请求超时（秒）	15
MCSM_ALLOW_WRITE	写操作开关	0（只读）
MCSM_COMMAND_WHITELIST	控制台指令白名单（逗号分隔前缀；空=全部允许）	空
MCSM_BLOCKED_COMMANDS	危险指令黑名单（按首词匹配）	stop,restart
MCSM_OPERATION_WAIT	mcs_wait_for_status 默认等待上限（秒）	600
MCSM_TRANSPORT	stdio 或 http	stdio
MCSM_HOST / MCSM_PORT	http 监听地址/端口	127.0.0.1 / 8000
MCSM_ENV_FILE	指定 .env 文件路径（可选）	.env

测试

.venv/Scripts/python tests/test_smoke.py   # stdio：tools/list + 无凭据/只读拦截/连接错误
.venv/Scripts/python tests/test_http.py    # streamable-http 握手与调用

安全提示

• 默认只读：启动/停止/重启/强停/发指令均需 MCSM_ALLOW_WRITE=1，请仅在可信客户端接入时开启。
• 指令黑名单默认拦截 stop/restart，防止通过控制台指令绕过面板操作；可再配白名单收紧。
• 面板凭据存放于 .env（已被 .gitignore 忽略）或环境变量，勿提交进仓库。
• 写工具返回 submitted=true 仅代表指令已下发（后台异步），完成确认请用 mcs_wait_for_status。

源码结构

src/mcsm_mcp/
├── __main__.py   # python -m mcsm_mcp 入口
├── server.py     # MCPServer + 8 个工具（mcp SDK 2.x）
├── api.py        # MCSManagerAPI 客户端（无 AstrBot 依赖，含 v9/v10 兼容）
└── config.py     # 环境变量配置 + 读写开关 + 指令白/黑名单策略