Skip to main content
Glama
minecraft-paper-mcp

minecraft-paper-mcp

minecraft-paper-mcp

MCP server for managing a Paper Minecraft server backend — runs on the same machine as the Minecraft server (direct file access and process control) alongside in-game commands via RCON

Features

  • Process control: server_start, server_stop, server_restart, server_status

  • RCON / in-game commands: rcon_command (any raw command), players_list, server_tps, server_say, player_kick, player_ban, player_pardon, player_op, player_deop, whitelist_add, whitelist_remove, give_item, teleport_player, set_gamerule, set_weather, set_time

  • File reading: whitelist_list, ops_list, banned_players_list, banned_ips_list, server_properties_get, server_properties_set (requires restart to take effect)

  • Logs: logs_tail (view the last N log lines), logs_search (grep with regex)

Related MCP server: Minecraft Server MCP

Installation

Requires Node.js 18 or higher

cd minecraft-mcp
npm install
npm run build

Preparing the Paper server

  1. Enable RCON in the Paper server's server.properties:

    enable-rcon=true
    rcon.port=25575
    rcon.password=ใส่รหัสผ่านที่ตั้งเอง_อย่าใช้ค่าว่าง
  2. Important: If the RCON port is exposed externally, you must block it with a firewall — RCON is not encrypted. It should only listen on 127.0.0.1 (the default) if the MCP server runs on the same machine.

  3. Restart the Paper server once for the RCON settings to take effect.

Setting up environment variables

There is a .env.example file for reference — copy it to .env and fill in the real values (the .env file is already in .gitignore and will not be committed to GitHub). The MCP server itself does not load .env automatically (it does not use dotenv) — set values via env in claude_desktop_config.json or export the variables before actually running. .env is only for keeping notes for yourself.

Variable

Default value

Description

MC_SERVER_DIR

current dir

path to the Paper server folder (containing paper.jar, server.properties, etc.)

MC_START_COMMAND

java -Xmx4G -Xms2G -jar paper.jar nogui

command for starting the server (adjust RAM/jar name as needed)

MC_RCON_HOST

127.0.0.1

RCON host

MC_RCON_PORT

25575

RCON port

MC_RCON_PASSWORD

(empty)

RCON password — must match server.properties

MC_PID_FILE

<MC_SERVER_DIR>/.mc-server.pid

file storing the PID of the started process

Setting up in Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "minecraft-paper": {
      "command": "node",
      "args": ["/absolute/path/to/minecraft-mcp/build/index.js"],
      "env": {
        "MC_SERVER_DIR": "/absolute/path/to/paper-server",
        "MC_START_COMMAND": "java -Xmx6G -Xms2G -jar paper-1.21.jar nogui",
        "MC_RCON_PASSWORD": "รหัสผ่านเดียวกับใน server.properties"
      }
    }
  }
}

Then restart Claude Desktop

CI

There is a GitHub Actions workflow (.github/workflows/build.yml) that runs npm install + npm run build on Node 18.x and 20.x on every push or PR into main to verify the project builds. If you want to use npm ci instead of npm install, run npm install once on your own machine to generate package-lock.json, then commit that file to the repo first.

Notes / Cautions

  • server_start/server_restart spawn a detached process and store the PID in MC_PID_FILE — if you want to run it as a real service (systemd), it still works, but the MCP will not recognize processes that systemd creates itself. Choose one approach (let this MCP start/stop it itself, or let systemd manage it and only use tools that rely on RCON/files).

  • server_stop will try to send the stop command via RCON first (graceful). If RCON cannot be reached, it falls back to SIGTERM.

  • server_properties_set edits the file directly — you must restart the server yourself for it to take effect (no auto-restart).

  • ban/kick/whitelist commands are done via RCON, not by editing the json files directly — safer while the server is running.

Available Tools

28 tools
banned_ips_listA

Read the current banned-ips.json contents.

Inputs: no named parameters.

banned_players_listA

Read the current banned-players.json contents.

Inputs: no named parameters.

give_itemC

Give an item to a player.

Inputs: item (required), player (required), amount.

logs_tailA

Get the last N lines of logs/latest.log.

Inputs: lines.

ops_listA

Read the current ops.json contents.

Inputs: no named parameters.

player_banC

Ban a player from the server.

Inputs: player (required), reason.

player_deopC

Revoke operator status from a player.

Inputs: player (required).

player_kickC

Kick a player from the server.

Inputs: player (required), reason.

player_opA

Grant operator status to a player.

Inputs: player (required).

player_pardonA

Unban a player.

Inputs: player (required).

players_listB

List currently online players.

Inputs: no named parameters.

rcon_commandA

Send a raw command to the server console via RCON (e.g. 'gamerule keepInventory true'). Use dedicated tools for common actions when available.

Inputs: command (required).

server_properties_getA

Read all key-value pairs from server.properties.

Inputs: no named parameters.

server_properties_setB

Set a single key in server.properties. Requires a server restart to take effect.

Inputs: key (required), value (required).

server_restartA

Restart the Minecraft server (graceful stop, wait 10s, then start).

Inputs: no named parameters.

server_sayB

Broadcast a chat message to all players.

Inputs: message (required).

server_startB

Start the Paper Minecraft server process.

Inputs: no named parameters.

server_statusA

Check whether the Minecraft server process is running, and get its PID.

Inputs: no named parameters.

server_stopA

Stop the Minecraft server. Sends 'stop' over RCON for a graceful shutdown, falling back to SIGTERM if RCON is unreachable.

Inputs: graceful.

server_tpsA

Get the server's current TPS (ticks per second) and MSPT stats.

Inputs: no named parameters.

set_gameruleC

Set a gamerule on the server.

Inputs: rule (required), value (required).

set_timeC

Set the in-game time.

Inputs: value (required).

set_weatherC

Change the weather.

Inputs: weather (required).

teleport_playerB

Teleport a player to another player or to coordinates.

Inputs: player (required), destination (required).

whitelist_addC

Add a player to the whitelist.

Inputs: player (required).

whitelist_listA

Read the current whitelist.json contents.

Inputs: no named parameters.

whitelist_removeB

Remove a player from the whitelist.

Inputs: player (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 28 tools

    Disambiguation5/5

    Each tool targets a clear and distinct action or resource, from server lifecycle to player moderation to log inspection. The generic rcon_command explicitly defers to dedicated tools, which reduces confusion rather than adding overlap.

    Naming Consistency3/5

    All names are snake_case and readable, but the set mixes resource-first names like player_kick and server_properties_get with verb-first names like give_item and set_time. There is also minor singular/plural inconsistency such as players_list versus player_kick.

    Tool Count2/5

    28 tools is on the heavy side for a Minecraft server admin server, exceeding the 25-tool threshold. Many tools are individually useful, but several could be consolidated, such as the multiple JSON file readers and properties get/set tools.

    Completeness4/5

    The surface covers server lifecycle, player moderation, whitelist/ops management, world settings, and log inspection well. Minor gaps exist around world save/backup operations and deeper player state queries, but common administrative workflows have no dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Provides comprehensive administrator-level control for Minecraft Java Edition servers, allowing AI to manage world generation, server configuration, and player moderation. It enables remote execution of RCON commands, NBT data parsing, and automated backup management through the Model Context Protocol.
      40
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with and manage Minecraft servers through a standardized interface, supporting server monitoring, player management, log analysis, and command execution.
      11
      1
      MIT