mcsrv-mcp-server

MCP Tools Server

MCP Tools Server is a Minecraft server plugin that provides an API for Large Language Models (LLMs) to interact with your Minecraft server. It leverages the Model Context Protocol (MCP) to expose server functionality as tools that can be called by AI assistants.

Features

• Server Logs Access: View server logs remotely through the API
• Chat Monitoring: Access player chat messages and Discord messages (via DiscordSRV)
• Command Execution: Execute Minecraft commands remotely
• MCP Compatibility: Follows the Model Context Protocol for seamless integration with LLMs
• DiscordSRV Integration: Connect your Minecraft server chat with Discord

Requirements

• Minecraft server running Paper/Spigot 1.19+
• Java 17 or higher
• DiscordSRV plugin (optional, for Discord integration)

Installation

1. Download the latest release JAR file from the Releases page
2. Place the JAR file in your server's plugins folder
3. Restart your server
4. The plugin will generate a default configuration file at plugins/MCPToolsServer/config.yml
5. Edit the configuration file to customize settings (see Configuration section)
6. Use /mcptools reload in-game to apply changes

Configuration

The plugin's configuration file (config.yml) contains the following sections:

mcp:
  server:
    port: 8080 # Port for the MCP server
    https: false # Whether to use HTTPS
    access-token: "" # Access token for authentication (empty = no auth)

logs:
  max-lines: 1000 # Maximum number of log lines to store
  include-console: true # Include console logs
  include-chat: true # Include player chat
  include-commands: true # Include command execution

chat:
  max-messages: 100 # Maximum number of chat messages to store
  include-discord: true # Include Discord messages

commands:
  allowed-prefixes: [] # Allowed command prefixes (empty = all)
  blocked-prefixes: # Blocked command prefixes
    - "op"
    - "deop"
    - "ban"
    - "kick"
    - "stop"
    - "reload"
  log-execution: true # Log command execution

API Usage

The plugin exposes an HTTP API that follows the Model Context Protocol (MCP). The API endpoints are:

• GET /info - Get server information
• GET /tools/list - List available tools
• POST /tools/call - Call a tool

Available Tools

1. View Logs (view_logs)

Retrieves server logs.

Parameters:

• limit (integer, optional): Number of log lines to return (default: 50, max: 1000)
• filter (string, optional): Filter logs by text
• logType (string, optional): Type of logs to return ("all", "console", "chat", "command")

Example Request:

{
  "name": "view_logs",
  "arguments": {
    "limit": 100,
    "filter": "error",
    "logType": "console"
  }
}

2. View Chat (view_chat)

Retrieves chat messages.

Parameters:

• limit (integer, optional): Number of messages to return (default: 20, max: 100)
• player (string, optional): Filter messages by player name
• includeDiscord (boolean, optional): Whether to include Discord messages (default: true)

Example Request:

{
  "name": "view_chat",
  "arguments": {
    "limit": 50,
    "player": "Steve",
    "includeDiscord": true
  }
}

3. Execute Command (execute_command)

Executes a Minecraft command.

Parameters:

• command (string, required): Command to execute (without leading slash)
• asConsole (boolean, optional): Whether to execute as console (default: true)
• player (string, optional): Player to execute as (only if asConsole is false)

Example Request:

{
  "name": "execute_command",
  "arguments": {
    "command": "time set day",
    "asConsole": true
  }
}

Example: Calling the API with curl

# List available tools
curl -X GET http://localhost:8080/tools/list

# View logs
curl -X POST http://localhost:8080/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name":"view_logs","arguments":{"limit":50}}'

# Execute a command
curl -X POST http://localhost:8080/tools/call \
  -H "Content-Type: application/json" \
  -d '{"name":"execute_command","arguments":{"command":"say Hello from API"}}'

Integration with LLMs

This plugin is designed to be used with Large Language Models that support the Model Context Protocol. The API allows LLMs to:

1. Discover available tools via the /tools/list endpoint
2. Call tools via the /tools/call endpoint
3. Process the results and take further actions

Commands and Permissions

• /mcptools reload - Reload the plugin configuration (Permission: mcptools.admin)
• /mcptools status - Show the current plugin status (Permission: mcptools.admin)

Building from Source

1. Clone the repository
2. Build using Maven:

   mvn clean package
   

3. The compiled JAR will be in the target directory

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.