Skip to main content
Glama
deenesjakoruzh
siwuli

mcsm-mcp

by siwuli
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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 无需重启），也可切换配置文件

Related MCP server: MCSManager MCP Server

与原插件的差异

原插件（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     # 环境变量配置 + 读写开关 + 指令白/黑名单策略
Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

View all tools

Related MCP Servers

View all related MCP servers

Related MCP Connectors

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/siwuli/mcp-server-mcs-manager'

If you have feedback or need assistance with the MCP directory API, please join our Discord server