Minecraft MCP Server

Minecraft-MCP-Server

Servidor MCP em Python para controlar um servidor Minecraft via RCON, usando FastMCP.

---

🔧 Recursos

• Expõe um conjunto de comandos (dicionário) para contextualizar o LLM
• Executa comandos no servidor Minecraft via RCON
• Integração com Claude Desktop ou qualquer cliente MCP
• Estrutura simples: stdio (desenvolvimento local) ou HTTP/SSE (produção)

---

📦 Estrutura do Projeto

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

---

⚙️ Instalação

1. Clone o repositório:

   cd Minecraft-MCP-Server/mcp_server
   

2. Crie um ambiente e instale as dependências:

   python -m venv venv
   venv\Scripts\activate
   pip install -r requirements.txt
   

---

📝 Configuração

No arquivo commands.json, você terá uma lista de comandos como /give, /weather, /gamemode, etc., com descrições e exemplos.

Não se esqueça de habilitar o RCON no arquivo server.properties do Minecraft:

enable-rcon=true
rcon.password=minemcp
rcon.port=25575

Crie um arquivo .env assim:

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

---

🚀 Executando o Servidor MCP

Ative o ambiente virtual e execute:

venv\Scripts\activate
python mcp_server/server.py

Monkey patch: inicia o servidor MCP em STDIO por padrão (apidog.com, reddit.com, github.com)

---

💬 Executando o Cliente de Chat (@ai)

Após iniciar o servidor, em um novo terminal, execute o cliente de chat:

venv\Scripts\activate
python mcp_server/mcp_chat_client.py

Este script monitora o log do servidor Minecraft e escuta mensagens de chat de jogadores que começam com @ai. Ele envia a mensagem para a API Gemini e executa o comando resultante no servidor via MCP.

⚠️

Importante: O servidor deve ser iniciado antes de executar o cliente.
A versão atual tem um bug conhecido de estouro de memória se o cliente iniciar antes do servidor.

---

⚙️ Integração com Claude Desktop

Em claude_desktop_config.json (ex.: %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%"}
    }
  }
}

Em seguida, reinicie o Claude — o servidor 'minecraft-controller' aparecerá.

---

🧪 Teste Local com 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())

---

🧰 Como Funciona

• 🎯 FastMCP carrega automaticamente ferramentas e recursos (medium.com, github.com)
• O recurso minecraft://commands fornece o dicionário de comandos
• A ferramenta run_minecraft_command usa mcrcon para enviar comandos ao Minecraft

---

📚 Referências

• [FastMCP v2 – README de exemplo] (pypi.org)
• [mcrcon – Cliente RCON em Python] (pypi.org)

---

🛠 Próximos Passos

• Suporte para transporte HTTP/SSE com Docker
• Validação/autocompletar de argumentos via dicionário de comandos
• Registro de ações extras: /start, /stop, /backup, /whitelist

---

Pronto para deixar seu servidor inteligente! 🚀