Skip to main content
Glama
deenesjakoruzh
siwuli

mcsm-mcp

by siwuli
OverviewSchemaRelated ServersScoreDiscussions
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:

  1. Edit servers/mcs-manager/.env (if it doesn't exist, first run cp .env.example .env);

  2. Call the mcs_reload_config tool to apply changes live, or simply restart the Server process;

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