Minecraft Ops MCP

Minecraft 서버 관리 및 운영을 위한 MCP stdio 서비스입니다. 현재 버전은 공식 MCP Python SDK를 기반으로 구현되었으며, 다음 백엔드를 지원합니다:

MCSManager API: 인스턴스 수명 주기, 로그, 파일 관리, 콘솔 명령.
RCON: 기존 콘솔 명령 대체 수단.
Minecraft Server Management Protocol (MSMP): Minecraft Java 1.21.9+용 JSON-RPC over WebSocket 관리 프로토콜.

문서

사용자 매뉴얼: docs/USER_MANUAL.md
개발자 프레임워크 설명: docs/DEVELOPER_GUIDE.md
현재 부족한 점 및 향후 로드맵: docs/LIMITATIONS.md
통합 테스트 보고서: docs/TEST_REPORT_2026-04-14.md
릴리스 체크리스트: docs/RELEASE_CHECKLIST.md
보안 설명: SECURITY.md
변경 로그: CHANGELOG.md

실행 방법

현재 Python 환경에 프로젝트 의존성을 설치한 후 실행하는 것을 권장합니다:

cd /home/damoc/codes/minecraft-ops-mcp
python3 -m pip install -e .
minecraft-ops-mcp

개발 및 디버깅 시 PYTHONPATH를 명시적으로 지정할 수도 있습니다:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -m minecraft_ops_mcp

개발 및 테스트

단위 테스트:

cd /home/damoc/codes/minecraft-ops-mcp
PYTHONPATH=src python3 -B -m unittest discover -s tests

문법 검사:

python3 -m compileall -q src scripts

프로토콜 수준 통합 프로브는 docs/TEST_REPORT_2026-04-14.md 및 docs/RELEASE_CHECKLIST.md를 참조하십시오.

MCP 클라이언트 구성 예시

{
  "mcpServers": {
    "minecraft-ops": {
      "command": "python3",
      "args": ["-m", "minecraft_ops_mcp"],
      "cwd": "/home/damoc/codes/minecraft-ops-mcp",
      "env": {
        "PYTHONPATH": "src",
        "MCSM_BASE_URL": "http://127.0.0.1:23333",
        "MCSM_API_KEY": "replace-me",
        "MCSM_DEFAULT_DAEMON_ID": "replace-me",
        "MCSM_DEFAULT_INSTANCE_UUID": "replace-me",
        "RCON_HOST": "127.0.0.1",
        "RCON_PORT": "25575",
        "RCON_PASSWORD": "replace-me",
        "MSMP_URL": "ws://127.0.0.1:25585",
        "MSMP_SECRET": "replace-me",
        "MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST": "list,time,help",
        "MINECRAFT_OPS_RAW_COMMAND_DENYLIST": "stop,op,deop,ban,ban-ip"
      }
    }
  }
}

.env.example을 참조하여 변수를 MCP 클라이언트 구성에 넣을 수도 있습니다. 이 서비스 자체는 런타임 구성 소스가 암시적으로 변하는 것을 방지하기 위해 .env 파일을 자동으로 읽지 않습니다.

주요 도구

MCSManager:

server.list_daemons
server.get_daemon_system
server.list_instances
server.get_instance
server.start
server.stop
server.restart
server.kill
server.send_command
server.get_logs
instance.create
instance.update_config
instance.update_config_patch
instance.clone_from_template
instance.delete
instance.reinstall
instance.run_update_task
file.list
file.read
file.download_prepare
file.download_local
file.upload_prepare
file.upload_local
file.upload_url
file.write
file.write_new
file.delete
file.move
file.copy
file.mkdir
file.touch
file.compress
file.uncompress

백엔드 간 공통 도구:

server.save_world: MSMP 우선, RCON 차순, MCSManager 마지막.
server.broadcast: MSMP 우선, RCON 차순, MCSManager 마지막.

RCON:

rcon.command
rcon.list_players
rcon.time_query
rcon.save_all

MSMP:

msmp.discover
msmp.call
msmp.players.list
msmp.players.kick
msmp.server.status
msmp.server.save
msmp.server.stop
msmp.bans.get
msmp.bans.add
msmp.bans.remove
msmp.bans.set
msmp.bans.clear
msmp.ip_bans.get
msmp.ip_bans.add
msmp.ip_bans.remove
msmp.ip_bans.set
msmp.ip_bans.clear
msmp.allowlist.get
msmp.allowlist.add
msmp.allowlist.remove
msmp.allowlist.set
msmp.allowlist.clear
msmp.operators.get
msmp.operators.add
msmp.operators.remove
msmp.operators.set
msmp.operators.clear
msmp.gamerules.get
msmp.gamerules.update
msmp.server_settings.get
msmp.server_settings.list
msmp.server_settings.set

보안 정책

고위험 작업에는 명시적 매개변수가 필요합니다:

{ "confirm": true }

에이전트가 무엇을 할지 먼저 설명하게 하려면 다음을 전달하십시오:

{ "dry_run": true }

고위험 도구에는 인스턴스 시작/중지/재시작/kill, 원시 명령, 파일 쓰기/삭제/이동/압축/압축 해제/업로드, MCP 로컬로 다운로드, 추방, 차단, 화이트리스트/OP/게임 규칙/서버 설정 수정 등이 포함됩니다. 모든 도구 호출은 감사 로그에 기록되며 기본 위치는 다음과 같습니다:

/tmp/minecraft-ops-mcp-audit.jsonl

MINECRAFT_OPS_AUDIT_LOG=를 비워두어 끌 수 있습니다.

원시 명령은 접두사 수준의 allowlist/denylist로 추가 제한할 수 있습니다:

MINECRAFT_OPS_RAW_COMMAND_ALLOWLIST=list,time,help
MINECRAFT_OPS_RAW_COMMAND_DENYLIST=stop,op,deop,ban,ban-ip

백엔드 권장 사항

인스턴스 수명 주기, 로그 및 파일 관리: MCSManager API를 우선 사용하십시오.
플레이어, 화이트리스트, OP, gamerule, server settings: MSMP를 우선 사용하십시오.
구버전 서버 또는 MSMP가 지원하지 않는 기능: RCON 또는 MCSManager 원시 명령을 대체 수단으로 사용하십시오.

RCON, MSMP, MCSManager API 키를 공용 네트워크에 노출하지 마십시오. MSMP/RCON은 localhost, VPN 또는 터널만 수신하도록 하는 것이 좋으며, MCSManager는 권한이 낮은 API 키를 사용하는 것이 좋습니다.

MSMP 매개변수 설명

msmp.call은 JSON-RPC params를 그대로 전달하므로 서버/버전 차이가 큰 새로운 메서드에 적합합니다:

{
  "method": "minecraft:server/status",
  "read_only": true
}

쓰기 작업 시 confirm=true를 사용하거나 먼저 dry_run=true를 사용하십시오. read_only=true는 rpc.discover, minecraft:players, minecraft:server/status, 목록 조회 및 server settings 읽기와 같이 화이트리스트에 있는 읽기 전용 MSMP 메서드에 대해서만 확인을 건너뜁니다.

Minecraft Ops MCP

Minecraft Ops MCP

문서

실행 방법

개발 및 테스트

MCP 클라이언트 구성 예시

주요 도구

보안 정책

백엔드 권장 사항

MSMP 매개변수 설명

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API