MinecraftServerMCP

Javadoc: v1.0.1

Spigot/Paper plugin that runs an embedded Model Context Protocol server over HTTP(S): tools and resources for the world directory, console, logs, and players, gated by bearer tokens and per-tool policies. Uses the MCP Java SDK (streamable HTTP).

Features

• MCP over HTTP(S) (Jetty); bind address, port, and path in config
• Bearer token or X-MCP-Token; per-profile YAML under access.<profile>.tools.<toolId>
• Built-in tools/resources: fs_read, fs_list, fs_write, server_command, server_logs, players_list, player_get
• Other plugins can register MCP tools via the Bukkit service MinecraftServerMcp
• /mcp reload reloads tokens and policies (does not unregister tools)

Requirements

Server operator setup

1. Install the shaded JAR from Releases (not *-plain.jar) into plugins/.
2. Start once, then edit plugins/MinecraftServerMCP/config.yml.
3. Set at least one access.<name>.token to a long random secret. The plugin disables itself if no tokens are configured.
4. Point MCP clients at http://<host>:<port><mcpPath> (defaults: 8765, /mcp) with header Authorization: Bearer <token> or X-MCP-Token: <token>.
5. Prefer bindAddress: "127.0.0.1" unless the client runs on another machine. Optional HTTPS is configured under ssl (requires a full restart to change).

Example listener + token:

bindAddress: "127.0.0.1"
port: 8765
mcpPath: "/mcp"

access:
  prod:
    token: "<use openssl rand -hex 32 or similar>"

Full keys: see config.yml (inline comments).

Example MCP client snippet

Don't forget to update the URL and credentials.

{
  "mcpServers": {
    "minecraft-server-mcp": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN"
      }
    }
  }
}

Built-in tools and resources

Policy YAML: access.<profile>.tools.<id>.

Use a prefix on custom tool names (e.g. myplugin_action) so they do not collide with built-ins.

Extending with another plugin

API reference: Javadoc v1.0.1 (MinecraftServerMcp, built-ins, config types).

1. Depend on this plugin

plugin.yml:

name: MyPlugin
# ...
softdepend: [MinecraftSer

... [View full README on GitHub](https://github.com/MrApik/MinecraftServerMCP#readme)