mc

This MCP server (mc) combines an AI agent system with a Minecraft-facing MCP server. The AIAgent (mc-server) handles tool orchestration and LLM interactions, while the MC server layer communicates with the Minecraft client using WebSocket connections and a script API to process game events. The system supports two request paths: external MCP clients can send requests to the AIAgent via the MCP front-end, and in-game players can trigger actions through chat commands that are listened for by the server. The server exposes an external MCP endpoint and a WebSocket-based channel for real-time communication, enabling seamless AI-assisted gameplay and tooling.

To run, you can start the server using either uv (recommended) or a direct Python invocation. With uv, the server is started as follows: uv run main.py --full --mcp. This launches the full MCP stack, including the AIAgent and the WebSocket MC server. If you prefer debugging, you can add --debug to log WebSocket packets and other internal data. If you run directly with Python, use: python main.py --full --mcp (to start the same stack). The server defaults to listening on port 8080 for the Minecraft connection, and the external MCP front-end is accessible at http://0.0.0.0:8000/sse when enabled.

Once running, you can interact through the MCP client by sending requests to the MCP front-end and observe responses from the AIAgent, which can invoke tools, call LLMs, and manage tool outputs. In-game interactions use the Minecraft Script API and WebSocket channel to feed game state and receive autonomous actions or tool results. The system is designed to integrate LLM-powered reasoning with in-game actions, providing a flexible interface for automating tasks, tool usage, and narrative-driven gameplay.

Prerequisites:

• Python 3.8+ (recommended isolation via virtualenv if desired)
• Git (optional, for cloning the repo)
• Access to install Python packages from PyPI

Installation steps:

1. Clone or download the repository containing the MCP server code (mc-mcp-server).
2. Create and activate a virtual environment (optional but recommended):
   • python3 -m venv venv
   • source venv/bin/activate # on Unix/macOS
   • venv\Scripts\activate # on Windows
3. Install dependencies:
   • pip install -r requirements.txt
4. Set required environment variables (example):
   • export DEEPSEEK_API_KEY=your_api_key # for API access used by LLM tools
5. Run the MCP server (choose one):
   • uv (recommended): uv run main.py --full --mcp
   • direct Python: python main.py --full --mcp

Notes:

• If you modify configuration files, ensure your changes are picked up by main.py at startup.
• The server will expose the external MCP interface and the WebSocket MC server once running.

Tips and known considerations:

• Environment variable DEEPSEEK_API_KEY is required for certain LLM tool integrations.
• Logs are saved under a logs directory; disable verbose logging in production if needed to reduce I/O.
• The external MCP front-end is accessible at the configured address (default http://0.0.0.0:8000/sse); ensure network security rules allow access.
• If the game or MCP client cannot connect, verify port 8080 for Minecraft WebSocket and 8000 for MCP front-end, and confirm that --full --mcp flags are used to enable the entire stack.
• When debugging, use --debug to capture detailed WebSocket packets for troubleshooting.