Minecraft Developer MCP

A lightweight MCP bridge for Spigot and Paper servers. It exposes console access, file reads/writes, plugin info, and log retrieval over HTTP so external tooling can automate server administration without FTP or screen sharing.

---

What It Can Do

• Run console commands and return captured output.
• Read or edit text files anywhere inside the server directory.
• Upload or download binary files via base64 (ideal for JARs or images).
• List installed plugins with their versions.
• Grab the last 100 lines from logs/latest.log.
• List files in any directory with sizes.

---

Tools & Example Requests

Tool	Description	Example request
execute_command	Run any console command with output capture.	Give 'Notch' a diamond sword named 'Excalibur'.
read_file	Read any text file (configs, logs, data) in the server dir.	Read plugins/Essentials/config.yml and show the chat format.
write_file	Create or edit files in place.	Create plugins/Skript/scripts/welcome.sk that greets players on join.
list_plugins	List installed plugins and versions.	Check if WorldGuard is enabled and up to date.
get_logs	Fetch the last 100 lines of latest.log.	Grab recent logs to see why the server lagged.
write_file_base64	Upload binary files via base64.	Upload SuperSword.jar to plugins/ and confirm size.
read_file_base64	Download binary files as base64.	Return world/icon.png as base64.
list_directory	List files in a folder with sizes.	List everything in world/region.

---

Quick Start

1. Install the Plugin

Download the latest JAR from the Releases Page and drop it into your plugins/ folder.

2. Configure and Secure

Start the server once to generate the config. Edit plugins/MCPMinecraft/config.yml:

server:
  port: 25374 # Choose an open port (ensure your host allows it)
  token: "CHANGE-THIS-TO-A-SECURE-RANDOM-TOKEN"

SECURITY WARNING: Anyone with this token has console access. Make it long and random.

3. Connect an MCP Client (example config)

Place this in your mcp.json (usually at ~/.cursor/mcp.json):

{
  "mcpServers": {
    "minecraft": {
      "url": "http://YOUR-SERVER-IP:25374/sse?token=YOUR-SECURE-TOKEN",
      "transport": "sse"
    }
  }
}

For scripting or automation you can also use the synchronous /api endpoint:

curl -X POST "http://YOUR-SERVER-IP:25374/api?token=YOUR-TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_plugins","arguments":{}}}'

4. Use It

• Backup whitelist.json, then add jeb_.
• Read bukkit.yml and adjust monster spawn limits.
• Tail the latest log entries before and after running a command.

---

Troubleshooting: No Extra Port?

If your host does not allow opening an extra port (e.g., some free providers), use a tunnel such as playit.gg:

1. Install the playit.gg plugin on your server.
2. Create a Custom TCP Tunnel pointing to 127.0.0.1:25374 (or whatever local port you configured).
3. Use the public address from playit (for example agent-tunnel.playit.gg:12345) in your mcp.json.

---

Build from Source

git clone https://github.com/center2055/MinecraftDeveloperMCP.git
cd MinecraftDeveloperMCP
mvn clean package

The shaded JAR will be in target/.