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