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、エージェントフレームワークなど）でプラグアンドプレイ利用できます。

ツール一覧（10 個）

ツール

説明

mcs_list_instances

全サーバーインスタンスを一覧表示（名前/状態/オンラインプレイヤー/ポート）

mcs_instance_status

指定インスタンスの状態詳細を照会（状態/オンラインプレイヤー/ポート/起動コマンド）

mcs_start_instance

指定インスタンスを起動（バックグラウンドで非同期実行）

mcs_stop_instance

指定インスタンスを正常停止（安全にセーブ）

mcs_restart_instance

指定インスタンスを再起動

mcs_kill_instance

指定インスタンスを強制停止（プロセスを kill、データ損失の可能性あり）

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