Minecraft-MCP-Server
Python MCP Server to control a Minecraft server via RCON, using FastMCP.
🔧 Features
- Exposes a set of commands (dictionary) to contextualize the LLM
- Executes commands on the Minecraft server via RCON
- Integration with Claude Desktop or any MCP client
- Simple structure:
stdio(local development) or HTTP/SSE (production)
📦 Project Structure
mcp_server/
├── __pycache__/
├── .env # Environment variables for Gemini and paths
├── commands.json # Commands dictionary and examples
├── mcp_chat_client.py # NEW: Client that listens to @ai messages from chat
├── server.py # Main MCP server
├── .gitattributes
├── .gitignore
├── readme.md
└── requirements.txt
⚙️ Installation
-
Clone the repository:
cd Minecraft-MCP-Server/mcp_server -
Create an environment and install dependencies:
python -m venv venv venv\Scripts\activate pip install -r requirements.txt
📝 Setup
In the commands.json file, you will have a list of commands like /give, /weather, /gamemode, etc., with descriptions and examples.
Don’t forget to enable RCON in the Minecraft server.properties file:
enable-rcon=true
rcon.password=minemcp
rcon.port=25575
Create a .env file like this:
MINECRAFT_LOG_PATH=C:\Users\YourUser\Desktop\mineserver\logs\latest.log
MCP_SERVER_PATH=mcp_server/server.py
GEMINI_API_KEY=your_gemini_api_key
🚀 Running the MCP Server
Activate the virtual environment and run:
venv\Scripts\activate
python mcp_server/server.py
Monkey patch: starts MCP server in STDIO by default (apidog.com, reddit.com, github.com)
💬 Running the Chat Client (@ai)
After starting the server, in a new terminal, run the chat client:
venv\Scripts\activate
python mcp_server/mcp_chat_client.py
This script monitors the Minecraft server log and listens for player chat messages that start with @ai. It sends the message to the Gemini API and executes the resulting command on the server via MCP.
⚠️ Important: The server must be started before running the client.
Current version has a known memory overflow bug if the client starts before the server.
⚙️ Integration with Claude Desktop
In claude_desktop_config.json (e.g., %APPDATA%\Claude\):
{
"mcpServers": {
"minecraft-controller": {
"type": "stdio",
"command": "/home/qkeq/Documentos/GitHub/Minecraft-MCP-Server/venv/bin/python3",
"args": ["C:\\...\\mcp_server\\server.py"],
"env": {"PATH": "%PATH%"}
}
}
}
Then restart Claude — the ‘minecraft-controller’ server will appear.
🧪 Local Test with Python
from fastmcp import Client
import asyncio
async def test():
client = Client("mcp_server/server.py")
async with client:
res = await client.call_tool("run_minecraft_command", {"command": "/list"})
print("Players:", res)
cmds = await client.read_resource("minecraft://commands")
print("Commands:", list(cmds.keys())[:5])
asyncio.run(test())
🧰 How It Works
- 🎯
FastMCPautomatically loads tools and resources (medium.com, github.com) - Resource
minecraft://commandsprovides the commands dictionary - Tool
run_minecraft_commandusesmcrconto send commands to Minecraft
📚 References
🛠 Next Steps
- Support for HTTP/SSE transport with Docker
- Argument validation/autocomplete via commands dictionary
- Logging extra actions:
/start,/stop,/backup,/whitelist
Ready to make your server smart! 🚀