Minecraftdevelopermcp

🚀 Minecraft Developer MCP

A lightweight MCP bridge for Spigot and Paper servers, enabling external tooling to automate server administration via HTTP.

This lightweight MCP bridge is designed for Spigot and Paper servers. It provides console access, file read/write capabilities, plugin information, and log retrieval over HTTP. This allows external tools to automate server administration without the need for FTP or screen - sharing.

✨ Features

• Run console commands and capture the output.
• Read or edit text files anywhere within the server directory.
• Upload or download binary files using base64 encoding (great for JARs or images).
• List installed plugins along with their versions.
• Retrieve the last 100 lines from logs/latest.log.
• List files in any directory with their sizes.

📦 Tools & Example Requests

🚀 Quick Start

1. Install the Plugin

Download the latest JAR from the Releases Page and place it in your plugins/ folder.

2. Configure and Secure

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

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

⚠️ Important Note

Anyone with this token can access the console. Make the token long and random.

3. Connect an MCP Client (example config)

Put the following 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.
• Check the latest log entries before and after running a command.

🔧 Troubleshooting: No Extra Port?

If your host doesn't allow opening an extra port (e.g., some free providers), you can use a tunnel like 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 the local port you configured).
3. Use the public address from playit (e.g., 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 located in the target/ directory.