What can you do with this server?

You can manage Minecraft server instances through MCSManager using MCP tools, with write operations gated by configuration. * List all instances with status, online players, and ports. * Query a specific instance’s status, players, port, and startup command. * Start, stop, restart, or force-kill an instance (write access required). * Send console commands such as say, list, op, whitelist, give, tp, etc., subject to command whitelist/blacklist policy. * Wait/poll until an instance reaches running or stopped after an operation. * View current effective configuration with secrets masked. * Hot-reload configuration from .env or environment variables without restarting the server.

How do I use mcsm-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcsm-mcp show me all Minecraft server instances and their status" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

de en es ja ko ru zh

mcsm-mcp

by siwuli

Overview Schema Source Related Servers Discussions Admin

Python

Remote

mcsm-mcp — MCSManager Minecraft Server Management MCP Server

A standalone MCP Server converted from the AstrBot plugin siwu-mcs-manager-1_0 (source plugin AstrBot _siwu-mcs-manager): Manages Minecraft server instances (list / status / start / stop / restart / kill / console commands) via the MCSManager panel API, ready for plug-and-play use with any MCP-capable client (Claude Desktop, IDEs, agent frameworks, etc.).

Tools at a Glance (10)

Tool	Description
`mcs_list_instances`	List all server instances (name/status/online players/port)
`mcs_instance_status`	Query detailed status of a specified instance (status/online players/port/start command)
`mcs_start_instance`	Start a specified instance (runs asynchronously in the background)
`mcs_stop_instance`	Gracefully stop a specified instance (safe save)
`mcs_restart_instance`	Restart a specified instance
`mcs_kill_instance`	Force-stop a specified instance (kills the process, may lose data)
`mcs_exec_command`	Send console commands to an instance (say/op/whitelist/give/tp/list, etc.)
`mcs_wait_for_status`	Poll until an instance reaches a target status (replaces the plugin's background push notifications)
`mcs_get_config`	View the currently active configuration (API Key/password are masked)
`mcs_reload_config`	Hot-reload configuration (no restart needed after editing .env), can also switch config files

Related MCP server: MCSManager MCP Server

Differences from the Original Plugin

Original plugin (AstrBot)	This MCP Server
Tools return Chinese text, and the LLM organizes the reply	Returns structured JSON, the caller organizes it itself
QQ group permissions (admin_ids / admin_role)	Read/write switch `MCSM_ALLOW_WRITE` (read-only by default), access control is handled by the calling client
Background polling + proactive push notifications after start/stop	`mcs_wait_for_status` is polled on demand by the LLM to confirm
Wake-word commands like `mc列表`	Handed to the client/LLM to use the tools directly (no chat context)
Forced agent tool hooks/system prompt injection	MCP tools are naturally exposed on demand by the client, no injection needed

Quick Start

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

Configuration (copy .env.example to .env and fill it in, or use environment variables directly):

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=允许启动/停止等

How to Modify Configuration (Plugin Config → MCP Config)

The original AstrBot plugin is configured in the admin panel; after MCP conversion, the config becomes the servers/mcs-manager/.env file (or environment variables). The mapping to the original plugin's config items is shown in the table below; default values are exactly the same:

Original plugin config item	MCP environment variable	Description
`mcs_base_url`	`MCSM_BASE_URL`	Panel address
`mcs_api_key`	`MCSM_API_KEY`	v10 API Key (recommended)
`mcs_username` / `mcs_password`	`MCSM_USERNAME` / `MCSM_PASSWORD`	Account/password login (v9)
`mcs_api_timeout`	`MCSM_TIMEOUT`	Request timeout (seconds)
`mcs_permission_enabled` + `mcs_admin_ids`/`mcs_admin_role`	`MCSM_ALLOW_WRITE`	QQ group permissions → read/write master switch (read-only by default)
`mcs_command_whitelist`	`MCSM_COMMAND_WHITELIST`	Command whitelist (comma-separated)
`mcs_blocked_commands`	`MCSM_BLOCKED_COMMANDS`	Command blacklist
`mcs_operation_wait`	`MCSM_OPERATION_WAIT`	Default wait seconds for the wait tool
`mcs_enabled`	— (enabled when the process starts)	No master switch needed; not starting the process disables it
`mcs_force_agent_tool`	— (meaningless)	MCP tools are exposed on demand by the client, no forced injection needed

Modification steps:

Edit servers/mcs-manager/.env (if it doesn't exist, first run cp .env.example .env);
Call the mcs_reload_config tool to apply changes live, or simply restart the Server process;
Use mcs_get_config to verify the active values (credentials are masked and shown as ***).

If you pass environment variables through the client config (e.g., the env block in the Claude Desktop config), call mcs_reload_config or restart after editing for the changes to take effect.

Running

stdio (local process, recommended):

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

HTTP (remote/multi-client):

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

Client Integration Example (stdio)

Claude Desktop's 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"
      }
    }
  }
}

Debugging: select stdio in npx @modelcontextprotocol/inspector and fill in the command/args above.

Full Environment Variables

Variable	Description	Default
`MCSM_BASE_URL`	Panel address (no trailing slash)	`http://127.0.0.1:23333`
`MCSM_API_KEY`	Panel API Key (v10 recommended)	empty
`MCSM_USERNAME` / `MCSM_PASSWORD`	Account/password login (v9 or when no Key is set)	empty
`MCSM_TIMEOUT`	Panel request timeout (seconds)	`15`
`MCSM_ALLOW_WRITE`	Write operation switch	`0` (read-only)
`MCSM_COMMAND_WHITELIST`	Console command whitelist (comma-separated prefixes; empty = allow all)	empty
`MCSM_BLOCKED_COMMANDS`	Dangerous command blacklist (matched by first word)	`stop,restart`
`MCSM_OPERATION_WAIT`	Default wait limit for `mcs_wait_for_status` (seconds)	`600`
`MCSM_TRANSPORT`	`stdio` or `http`	`stdio`
`MCSM_HOST` / `MCSM_PORT`	http listen address/port	`127.0.0.1` / `8000`
`MCSM_ENV_FILE`	Specify the .env file path (optional)	`.env`

Testing

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

Security Notes

Read-only by default: start/stop/restart/kill/send-command all require MCSM_ALLOW_WRITE=1; only enable it when connecting trusted clients.
The command blacklist blocks stop/restart by default to prevent bypassing panel operations via console commands; you can further tighten it with a whitelist.
Panel credentials are stored in .env (ignored by .gitignore) or environment variables; do not commit them to the repository.
A write tool returning submitted=true only means the command has been dispatched (asynchronous in the background); use mcs_wait_for_status to confirm completion.

Source Structure

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     # 环境变量配置 + 读写开关 + 指令白/黑名单策略

Available Tools

10 tools

mcs_exec_commandA

向指定的 Minecraft 服务器实例发送控制台指令，如 say 发送公告、list 查看在线玩家、op 设置管理员、whitelist 管理白名单、give 发放物品、tp 传送、kick/ban 管理玩家、time/weather/gamemode/difficulty 等。指令在服务端控制台执行。用于「给XX服发个公告」「在XX服执行 op Steve」「把某人加进XX服白名单」「XX服有多少人在线」等请求。

Args: instance_name: 服务器实例名称或实例 UUID，如生存服、SMP command: 控制台指令（不含 / 前缀），如 say 大家好、list、op Steve、whitelist add Steve

Inputs: command (required), instance_name (required). Returns: object

mcs_get_configA

查看当前 MCP Server 生效的配置：面板地址、读写开关、指令白/黑名单、传输方式等（API Key 与密码已脱敏为 ***）。用于确认 Server 当前配置状态，或修改 .env 后核对是否生效。

Inputs: no named parameters. Returns: object

mcs_instance_statusA

查询指定 Minecraft 服务器实例的运行状态与详情，包括运行状态、在线玩家数、端口、启动命令。用于回答「XX服务器状态怎么样」「XX服在线多少人」「XX服开没开」等问题。

Args: instance_name: 服务器实例名称（MCSManager 中配置的昵称）或实例 UUID，如生存服、SMP、我的世界主服

Inputs: instance_name (required). Returns: object

mcs_kill_instanceA

强制停止指定的 Minecraft 服务器实例（直接杀进程，可能丢失未保存数据，仅建议在正常停止无效时使用）。用于「强制关掉XX服」「XX服卡死了，强停一下」等请求。

Args: instance_name: 服务器实例名称或实例 UUID，如生存服、SMP

Inputs: instance_name (required). Returns: object

mcs_list_instancesA

列出 MCSManager 面板上的所有 Minecraft 服务器实例，包括名称、运行状态、在线玩家数、端口。用于回答「有哪些服务器」「服务器列表」「各服务器现在什么状态」等问题。返回结构化列表 JSON。

Inputs: no named parameters. Returns: object

mcs_reload_configA

重新加载配置（.env 文件或环境变量），不需要重启 Server 即可生效。修改 .env 后调用本工具立即热更新；也可传 env_file 切换到另一个配置文件。

Args: env_file: 可选的 .env 文件路径（留空则沿用启动时使用的路径；纯环境变量模式则重读当前环境变量）

Inputs: env_file. Returns: object

mcs_restart_instanceA

重启指定的 Minecraft 服务器实例。重启为后台异步执行；如需确认完成，可随后调用 mcs_wait_for_status(instance_name, "running")。用于「重启一下XX服」「XX服务器卡了，重启一下」等请求。

Args: instance_name: 服务器实例名称或实例 UUID，如生存服、SMP

Inputs: instance_name (required). Returns: object

mcs_start_instanceA

启动指定的 Minecraft 服务器实例。启动在 MCS 后台异步执行，指令下发后立即返回；如需确认启动完成，可随后调用 mcs_wait_for_status(instance_name, "running")。用于「启动XX服务器」「把XX服开起来」等请求。

Args: instance_name: 服务器实例名称（MCSManager 中配置的昵称）或实例 UUID，如生存服、SMP、我的世界主服

Inputs: instance_name (required). Returns: object

mcs_stop_instanceA

正常停止指定的 Minecraft 服务器实例（向服务端发送停止指令，可安全存档）。停止为后台异步执行；如需确认完成，可随后调用 mcs_wait_for_status(instance_name, "stopped")。用于「关掉XX服」「把XX服务器停下来」等请求。

Args: instance_name: 服务器实例名称或实例 UUID，如生存服、SMP

Inputs: instance_name (required). Returns: object

mcs_wait_for_statusA

等待指定服务器实例达到目标状态（每 5 秒轮询一次），用于启动/停止/重启后确认操作完成——替代原插件“后台推送通知”能力。达到目标状态返回 reached=true，超时返回 reached=false 并附当前状态。

Args: instance_name: 服务器实例名称或实例 UUID，如生存服、SMP target_status: 目标状态：running（运行中）或 stopped（已停止），也接受中文运行中/已停止 timeout_seconds: 最长等待秒数（默认 300，范围 5~1800）

Inputs: instance_name (required), target_status (required), timeout_seconds. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored 2026-08-25 10:55 across 10 tools

Disambiguation5/5

每个工具都有明确的目的：列表、状态、启动、停止、重启、强制停止、命令执行、等待状态以及配置管理。即使像停止和强制停止这样的操作也有不同的描述，防止混用。

Naming Consistency4/5

所有工具都以 'mcs_' 作为前缀，并且大多遵循动词-名词模式（list_instances、start_instance、wait_for_status 等）。唯一例外是 'mcs_instance_status'，缺少动作动词，但其余部分保持一致。

Tool Count5/5

10 个工具非常适合管理 MCSManager 实例，覆盖了核心操作而不显得臃肿。每个工具都服务于不同的需求，没有不必要的重复。

Completeness5/5

工具集提供了完整的生命周期覆盖（列出、状态、启动、停止、重启、强制停止），并结合了命令执行和状态等待。配置管理工具也功能齐全。对于预期的领域没有明显的缺口。

Maintenance

ActivityMaintained

ResponsivenessOutdated data

Resources

Related MCP Connectors

mcpA
com.fadehost
Manage FadeHost game servers, Discord bots and VPS: console, stats, backups, logs, lifecycle.
Games & Gamification Virtualization
391
https://api.fadehost.com/mcp
Tacyon MC
io.tacyon
Create, configure, manage Minecraft servers — plugins, files, console, modpacks, backups, metrics.
Games & Gamification Shell Access File Systems
2
https://portal.tacyon.io/api/mcp
xCloud
host.xcloud
Official xCloud MCP: manage servers, sites, WordPress, SSL, backups and deploys from any MCP client.
Cloud Platforms Content Management Systems CI/CD & DevOps
1
https://app.xcloud.host/mcp
ZapX by ZAP-HostingBDeprecated
com.zap-hosting
Manage ZAP-Hosting game servers, VPS, dedicated servers, TeamSpeak and domains from your AI client.
Cloud Platforms Virtualization Networking & Infrastructure
2311
https://zap-hosting.com/api/mcp

Related MCP Servers

MCSManager MCP Server
Games & Gamification OS Automation App Automation
chaofanx
A
license
Not graded
quality
D
maintenance
Enables management of Minecraft servers through the MCSManager API. Supports executing server commands, checking player status, retrieving server information, and controlling game settings like weather.
Updated a year ago (2025-09-08 14:15 UTC)
16 npm
1
MIT
MCSManager MCP Server
App Automation Games & Gamification Virtualization
SMGoro
F
license
Not graded
quality
D
maintenance
Enables AI agents to manage Minecraft servers through MCSManager, including instance control (start/stop/restart), file management, scheduled tasks, user management, and backup operations.
Updated a year ago (2025-11-25 21:04 UTC)
5
-
Pterodactyl MCP Server
Games & Gamification Virtualization
Ethereal-Jay
A
license
Not graded
quality
D
maintenance
Enables managing Pterodactyl Game Panel servers via Client and Application APIs, including power actions, files, databases, backups, schedules, and administrative operations.
Updated 5 months ago (2026-06-28 01:51 UTC)
115 npm
MIT
pebblehost-mcp
bop-del
A
license
Not graded
quality
D
maintenance
Enables natural language management of Pebblehost Minecraft servers, including server status, control, console commands, file management, and backups.
Updated 9 months ago (2026-02-15 16:27 UTC)
MIT

mcsm-mcp — MCSManager Minecraft Server Management MCP Server

Tools at a Glance (10)

Differences from the Original Plugin

Quick Start

How to Modify Configuration (Plugin Config → MCP Config)

Running

Client Integration Example (stdio)

Full Environment Variables

Testing

Security Notes

Source Structure

Available Tools

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

MCSManager MCP Server

MCSManager MCP Server

Pterodactyl MCP Server

pebblehost-mcp