Minecraft MCP Server

# 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 1. Clone the repository: ```bash cd Minecraft-MCP-Server/mcp_server ``` 2. Create an environment and install dependencies: ```bash 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: ```bash venv\Scripts\activate python mcp_server/server.py ``` Monkey patch: starts MCP server in STDIO by default ([apidog.com][1], [reddit.com][2], [github.com][3]) --- ## 💬 Running the Chat Client (`@ai`) After starting the server, in a new terminal, run the chat client: ```bash 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\`): ```json { "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 ```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 * 🎯 `FastMCP` automatically loads tools and resources ([medium.com][4], [github.com][5]) * Resource `minecraft://commands` provides the commands dictionary * Tool `run_minecraft_command` uses `mcrcon` to send commands to Minecraft --- ## 📚 References * [FastMCP v2 – Sample README] ([pypi.org][6]) * [mcrcon – Python RCON client] ([pypi.org][6]) --- ## 🛠 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!** 🚀 [1]: https://apidog.com/blog/fastmcp/?utm_source=chatgpt.com "A Beginner's Guide to Use FastMCP - Apidog" [2]: https://www.reddit.com/r/mcp/comments/1hrq0au/how_to_build_mcp_servers_with_fastmcp_stepbystep/?utm_source=chatgpt.com [3]: https://github.com/GanonUchiha/My-FastMCP-Example?utm_source=chatgpt.com [4]: https://medium.com/data-engineering-with-dremio/building-a-basic-mcp-server-with-python-4c34c41031ed?utm_source=chatgpt.com [5]: https://github.com/jlowin/fastmcp?utm_source=chatgpt.com [6]: https://pypi.org/project/mcrcon/?utm_source=chatgpt.com