Claude가 MasterControl API를 통해 Minecraft 명령어를 실행하고 탭 완성을 가져올 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.
이 MCP 서버는 두 가지 도구를 제공합니다:
execute_command인증된 플레이어로서 원격으로 Minecraft 명령어를 실행합니다.
플레이어는 온라인 상태여야 하며 서버에 접속해 있어야 합니다.
명령어가 실행되면 플레이어는 게임 내 알림을 받습니다.
명령어 출력 또는 오류 메시지를 반환합니다.
도움말 보기: 명령어 뒤에 "help"를 붙이세요 (예: "island help", "island upgrade help")
예시:
execute_command("gamemode creative")
execute_command("island help") # Shows island command help
execute_command("island upgrade help") # Shows upgrade subcommand help
execute_command("island upgrade speed 5")tab_complete부분적인 명령어에 대한 탭 완성 제안을 가져옵니다.
사용 가능한 명령어 및 하위 명령어 탐색
유효한 인수 및 매개변수 찾기
Minecraft에서 Tab 키를 누르는 것과 정확히 동일하게 작동합니다.
예시:
tab_complete("gamemode ") # Returns: survival, creative, adventure, spectator
tab_complete("island ") # Returns: available island subcommandsRelated MCP server: MCP Minecraft Remote
Python 3.10 이상
uv 패키지 관리자 (여기서 설치)
명령어 API가 실행 중인 MasterControl 서버
Minecraft 플레이어를 위한 유효한 API 키
저장소 복제:
git clone https://github.com/<your-user>/minecraft-mcp-server.git
cd minecraft-mcp-server의존성 설치:
uv sync환경 변수 구성:
cp .env.example .env설정으로 .env 편집:
# Required: Your Midnight API key
MIDNIGHT_API_KEY=your-api-key-here
# Optional: MasterControl API URL (defaults to localhost:8080)
MIDNIGHT_API_URL=http://your-server:8080/api/v2서버를 직접 실행하여 테스트합니다:
uv run server.pystdio 입력을 기다리게 되며, 이는 MCP 서버에서 정상적인 동작입니다. 종료하려면 Ctrl+C를 누르세요.
Claude Code에 서버를 추가합니다 (복제된 저장소의 절대 경로를 사용하세요):
claude mcp add midnight \
--transport stdio \
--env MIDNIGHT_API_KEY=your-key-here \
--env MIDNIGHT_API_URL=http://localhost:8080/api/v2 \
-- uv --directory /absolute/path/to/minecraft-mcp-server run server.pyClaude Code에서 서버가 실행 중인지 확인합니다:
/mcpmidnight가 상태 ✓ Connected로 나열되어야 합니다.
명령어 실행:
You: "Change my gamemode to creative"
Claude: [Uses execute_command("gamemode creative")]
✓ Command executed successfully명령어 도움말 보기:
You: "How do I use the island upgrade command?"
Claude: [Uses execute_command("island upgrade help")]
Shows the help output for island upgrade명령어 탐색:
You: "What island commands are available?"
Claude: [Uses tab_complete("island ")]
Lists: upgrade, create, delete, invite, members...변수 | 필수 | 기본값 | 설명 |
| 예 | - | 플레이어의 API 키 |
| 아니오 |
| MasterControl API 기본 URL |
POST /api/v2/command/execute — 명령어 실행
POST /api/v2/command/tabComplete — 탭 완성 가져오기
.env 파일을 생성하세요:
echo "MIDNIGHT_API_KEY=your-key-here" > .env다음 사항을 확인하세요:
MasterControl API가 실행 중인지
API 키가 올바른지
플레이어가 온라인 상태이며 서버에 접속해 있는지 (프록시 대기 상태가 아님)
.env 파일을 절대 커밋하지 마세요 — API 키가 포함되어 있습니다 (.gitignore를 통해 이미 제외됨)
명령어는 플레이어의 권한으로 실행됩니다
AI는 사용자가 게임 내에서 실행할 수 있는 모든 명령어를 실행할 수 있습니다
Execute a Minecraft command remotely as the authenticated player.
This tool allows you to run any Minecraft command as if the player associated with the API key typed it in-game. The player must be online and on a server. The player will be notified in-game that a remote command is being executed.
To get help for any command, simply append "help" as the last argument. For example: "island help", "island upgrade help", "gamemode help"
Args: command: The Minecraft command to execute (without the leading slash). Examples: "gamemode creative", "tp 100 64 200", "island upgrade speed 5"
Returns: The output from the command execution, or an error message if it failed.
Examples: - execute_command("help") - Shows general help - execute_command("island help") - Shows island command help - execute_command("island upgrade help") - Shows island upgrade help - execute_command("gamemode survival") - Changes gamemode
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behavioral traits: the player will be notified in-game, the command executes as the authenticated player, and it returns output or error messages. It covers the essential mutation behavior and user feedback mechanism, though it doesn't mention rate limits or specific error handling details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with the core purpose, then provides usage details, parameter explanation, return values, and examples. Every sentence adds value, with no redundant information, and it's front-loaded with the most important information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (remote command execution with authentication requirements), no annotations, and an output schema exists, the description provides excellent completeness. It covers purpose, prerequisites, parameter usage, return behavior, and multiple examples. The output schema handles return value structure, so the description appropriately focuses on operational context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must fully compensate. It provides comprehensive parameter semantics: explains what the 'command' parameter is ('The Minecraft command to execute without the leading slash'), gives multiple examples, and shows how to get help. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Execute a Minecraft command remotely as the authenticated player') and distinguishes it from the sibling tool 'tab_complete' by focusing on command execution rather than completion suggestions. It specifies the resource (Minecraft command) and the context (remote execution as authenticated player).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('run any Minecraft command as if the player associated with the API key typed it in-game'), including prerequisites (player must be online and on a server). It doesn't explicitly mention when not to use it or provide detailed alternatives beyond the sibling tool, but the context is well-defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tab completion suggestions for a partial Minecraft command.
This tool provides autocomplete suggestions for commands, just like pressing Tab in the Minecraft client. Useful for discovering available commands, subcommands, and valid arguments.
Args: command_line: The partial command line to complete. Examples: "gamemode ", "island upgrade ", "give diamond"
Returns: A formatted list of completion suggestions, or a message if none are available.
Examples: - tab_complete("gamemode ") -> Lists: survival, creative, adventure, spectator - tab_complete("island ") -> Lists available island subcommands - tab_complete("give ") -> Lists available items
| Name | Required | Description | Default |
|---|---|---|---|
| command_line | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool does (provides autocomplete suggestions), the context (like pressing Tab in Minecraft), and the return behavior (formatted list or message if none available). It doesn't mention rate limits or error handling, but covers the core behavior well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with a clear purpose statement, follows with usage guidelines, then provides parameter details, return information, and concrete examples. Every sentence adds value with zero wasted content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (single parameter, no annotations, but with output schema), the description is complete. It explains the purpose, usage, parameter with examples, and return behavior. The existence of an output schema means the description doesn't need to detail return values, and it adequately covers what's needed for this autocompletion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It provides a clear parameter description: 'command_line: The partial command line to complete' with three concrete examples that illustrate valid inputs. This adds significant meaning beyond the bare schema, though it doesn't detail all possible command formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get tab completion suggestions for a partial Minecraft command.' It specifies the exact action (get suggestions) and resource (Minecraft commands), and distinguishes it from the sibling tool 'execute_command' by focusing on autocompletion rather than command execution.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states when to use this tool: 'Useful for discovering available commands, subcommands, and valid arguments.' It provides clear context for its purpose (autocompletion like pressing Tab) and distinguishes it from the alternative 'execute_command' by not overlapping in functionality.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0execute_commandtab_completeScored across 2 tools
The two tools have clearly distinct purposes: execute_command runs commands, while tab_complete provides suggestions for command completion. There is no overlap or ambiguity between them, as one is for execution and the other is for discovery/assistance.
Both tools follow a consistent verb_noun naming pattern (execute_command and tab_complete). The naming is clear, predictable, and uses the same style throughout, making it easy to understand their functions at a glance.
With only 2 tools, the server feels thin for its purpose of Minecraft command execution. While the tools cover basic execution and completion, there are likely missing operations such as listing available commands, checking player status, or handling command history, which would enhance the server's utility and completeness.
The tool set is severely incomplete for the domain of Minecraft command execution. It lacks essential operations like listing all available commands, validating commands before execution, managing multiple players, or handling command feedback in a structured way. This forces agents to rely heavily on trial-and-error with execute_command and tab_complete, leading to potential inefficiencies and failures.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
Generate AI images and videos from any compatible MCP client.
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
