# MineMCP<\/p>\n
\n
\n<\/p>\n
A Minecraft Paper plugin that implements the Model Context Protocol (MCP) server, enabling AI agents to control and monitor a Minecraft 1.21 server via HTTP.<\/p>\n
## \ud83d\udee0\ufe0f Available Tools<\/p>\n
### World Manipulation
\n– `pose_block` – Place a block at specific coordinates
\n– `break_block` – Break a block at specific coordinates
\n– `fill_block` – Fill a region with blocks<\/p>\n
### Command Execution
\n– `execute_command` – Execute any Minecraft command with output capture<\/p>\n
### File System
\n– `read_file` – Read text files from the server
\n– `write_file` – Write text files to the server
\n– `read_file_base64` – Read binary files as Base64
\n– `write_file_base64` – Write binary files from Base64
\n– `list_directory` – List directory contents<\/p>\n
### Server Information
\n– `list_plugins` – Get all installed plugins
\n– `get_logs` – Retrieve recent server logs
\n– `get_online_players` – List all online players
\n– `get_player` – Get detailed information about a specific player (health, inventory, location, effects, etc.)<\/p>\n
## \ud83d\udccb Requirements<\/p>\n
– **Java 21** or higher
\n– **Minecraft 1.21** server
\n– **Paper** or **Purpur** server software (Spigot may work but not officially supported)<\/p>\n
## \ud83d\ude80 Installation<\/p>\n
### Download Pre-built JAR<\/p>\n
1. Download the latest release from the [Releases](..\/..\/releases) page
\n2. Place `MineMCP-1.0.0-all.jar` in your server’s `plugins\/` folder
\n3. Start\/restart your server
\n4. Configure the token in `plugins\/MineMCP\/config.yml`<\/p>\n
## \u2699\ufe0f Configuration<\/p>\n
After the first run, edit `plugins\/MineMCP\/config.yml`:<\/p>\n
“`yaml
\nserver:
\n port: 3000
\n token: “your-secret-token-here” # Change this to a secure random token!
\n“`<\/p>\n
**Important**: Always change the default token for security!<\/p>\n
### Generating a Secure Token<\/p>\n
“`bash
\n# Linux\/macOS
\nopenssl rand -hex 32<\/p>\n
# Or use any password generator to create a strong token
\n“`<\/p>\n
## \ud83d\udd0c Usage<\/p>\n
### Starting the Server<\/p>\n
1. Start your Minecraft server with MineMCP installed
\n2. The MCP server will automatically start on port 3000 (configurable)
\n3. Check the console for: `[MineMCP] MCP server started on port 3000`<\/p>\n
### Connecting with an MCP Client<\/p>\n
#### Using VS Code with MCP Extension<\/p>\n
Create or edit `.vscode\/mcp.json` in your project:<\/p>\n
“`json
\n{
\n “mcpServers”: {
\n “minecraft”: {
\n “url”: “http:\/\/localhost:3000\/sse?token=your-secret-token-here”
\n }
\n }
\n}
\n“`<\/p>\n
## \ud83d\udcda API Examples<\/p>\n
### Execute a Command<\/p>\n
“`json
\n{
\n “jsonrpc”: “2.0”,
\n “id”: 1,
\n “method”: “tools\/call”,
\n “params”: {
\n “name”: “execute_command”,
\n “arguments”: {
\n “command”: “time set day”
\n }
\n }
\n}
\n“`<\/p>\n
### Place a Block<\/p>\n
“`json
\n{
\n “jsonrpc”: “2.0”,
\n “id”: 2,
\n “method”: “tools\/call”,
\n “params”: {
\n “name”: “pose_block”,
\n “arguments”: {
\n “world”: “world”,
\n “x”: 100,
\n “y”: 64,
\n “z”: 200,
\n “material”: “DIAMOND_BLOCK”
\n }
\n }
\n}
\n“`<\/p>\n
### Get Player Information<\/p>\n
“`json
\n{
\n “jsonrpc”: “2.0”,
\n “id”: 3,
\n “method”: “tools\/call”,
\n “params”: {
\n “name”: “get_player”,
\n “arguments”: {
\n “player”: “PlayerName”,
\n …
\n }
\n }
\n}
\n“`<\/p>\n
## \ud83d\udd12 Security Considerations<\/p>\n
1. **Token Protection**: Never commit your token to version control
\n2. **Network Security**: By default, the server binds to `0.0.0.0` (all interfaces)
\n3. **Firewall Rules**: Restrict port 3000 access to trusted IPs only
\n4. **File System Access**: Tools have access to the entire server directory – use with caution<\/p>\n
## \ud83e\udd1d Contributing<\/p>\n
Contributions are welcome! Please follow these steps:<\/p>\n
1. Fork the repository
\n2. Create a feature branch (`git checkout -b feature\/amazing-feature`)
\n3. Commit your changes (`git commit -m ‘Add amazing feature’`)
\n4. Push to the branch (`git push origin feature\/amazing-feature`)
\n5. Open a Pull Request<\/p>\n
### Adding a New Tool<\/p>\n
1. Create a new class extending `McpTool` in `src\/main\/java\/me\/axeno\/minemcp\/tools\/impl\/`
\n2. Implement the required methods (`getSchema()` and `execute()`)
\n3. Register the tool in `ToolHandler.java` constructor<\/p>\n
Example:<\/p>\n
“`java
\npublic class MyTool extends McpTool {
\n public MyTool() {
\n super(“my_tool”, “Description of my tool”);
\n }<\/p>\n
@Override
\n public ObjectNode getSchema() {
\n ObjectNode schema = mapper.createObjectNode();
\n schema.put(“type”, “object”);
\n \/\/ Define your schema…
\n return schema;
\n }<\/p>\n
@Override Bukkit.getScheduler().runTask(MineMCP.getInstance(), () -> { String result = future.get(10, TimeUnit.SECONDS); ## \ud83d\udcc4 License<\/p>\n This project is licensed under the MIT License – see the [LICENSE](LICENSE) file for details.<\/p>\n ## \ud83d\udcde Support<\/p>\n – **Issues**: [GitHub Issues](..\/..\/issues)<\/p>\n —<\/p>\n Made with \u2764\ufe0f for the Minecraft and AI communities<\/p>\n","protected":false},"excerpt":{"rendered":" An MCP server implementation bridging AI agents and Minecraft.<\/p>\n","protected":false},"featured_media":102352,"template":"","meta":{"_minecraft_slug":"minemcp","_minecraft_project_id":"KemmI7Uv","_minecraft_author":"Axeno","_minecraft_license":"GPL-3.0-only","_minecraft_downloads":16,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"minemcp.zip","_minecraft_size_bytes":16642310,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T22:47:43.470690Z","_minecraft_date_created":"2026-02-02T19:52:54.388585Z","_minecraft_date_modified":"2026-02-01T14:17:26.710733Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/minemcp","_minecraft_icon_attachment_id":102352,"_minecraft_imported_at":"2026-06-05T21:07:50+00:00","_minecraft_import_hash":"53f877a04dffa6099a6dcd5c8729aced","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[89,127,92],"mod_loader":[132],"minecraft_version":[62,37,40,41,73,74,38,78,79,80,81,82],"class_list":["post-102351","mod","type-mod","status-publish","has-post-thumbnail","hentry","mod_category-game-mechanics","mod_category-paper","mod_category-utility","mod_loader-paper","minecraft_version-1-21","minecraft_version-1-21-1","minecraft_version-1-21-10","minecraft_version-1-21-11","minecraft_version-1-21-2","minecraft_version-1-21-3","minecraft_version-1-21-4","minecraft_version-1-21-5","minecraft_version-1-21-6","minecraft_version-1-21-7","minecraft_version-1-21-8","minecraft_version-1-21-9"],"yoast_head":"\n
\n public ObjectNode execute(JsonNode args) throws Exception {
\n CompletableFuture
\n try {
\n \/\/ Your Bukkit operations here
\n future.complete(“Success!”);
\n } catch (Exception e) {
\n future.completeExceptionally(e);
\n }
\n });<\/p>\n
\n return createTextResult(result);
\n }
\n}
\n“`<\/p>\n