Content
# MODPC MCP Server
Encapsulates Minecraft (modpc) game capabilities as MCP (Model Context Protocol) tools for LLM Agent to call,
enabling large models to directly drive in-game players: movement, block placement/destruction, entity summoning, UI operation, etc.
## Architecture
```
LLM Agent ←──MCP over HTTP──→ modpc MCP Server ←──TCP Socket──→ Game Listener Service
(Claude, etc.) /mcp :3002 (this project, Python 3) 4-byte length header + JSON (:14520, provided by dev package)
```
This project is merely the bridge layer between **MCP ↔ Game**. The actual game capabilities are implemented by the game end.
## Prerequisites
- **Python 3.10+**
- **modpc Development Package**: After installation and entering the game (entering any save), the game end will **automatically open the Socket listener on port `14520`**.
This service connects to this port to communicate with the game. If the game is not running or no save is entered, calling the tool will return `Cannot connect to game`.
## Installation
```bash
cd modpc_mcp_server
pip install -r requirements.txt
```
## Running
```bash
# Default: HTTP listen on 0.0.0.0:3002, game end on 127.0.0.1:14520
python server.py
# Custom ports
python server.py --game-port 14520 --http-port 3002
```
After startup, the MCP endpoint is `http://<host>:3002/mcp` (Streamable HTTP transmission).
Available parameters:
| Parameter | Default value | Description |
|------|--------|------|
| `--game-host` | `127.0.0.1` | Game end Socket host |
| `--game-port` | `14520` | Game end Socket port |
| `--http-host` | `0.0.0.0` | MCP HTTP listen address |
| `--http-port` | `3002` | MCP HTTP listen port |
## Configuring to Coding / Agent Tools
This service uses **Streamable HTTP** transmission. First, run the server according to the above steps, then configure the MCP endpoint in the tool.
### Claude Code
```bash
claude mcp add --transport http modpc http://127.0.0.1:3002/mcp
```
Or manually add in the project `.mcp.json` / user configuration:
```json
{
"mcpServers": {
"modpc": {
"type": "http",
"url": "http://127.0.0.1:3002/mcp"
}
}
}
```
### Cursor
Edit `~/.cursor/mcp.json` (or project `.cursor/mcp.json`):
```json
{
"mcpServers": {
"modpc": {
"url": "http://127.0.0.1:3002/mcp"
}
}
}
```
### Other Tools Supporting MCP
Any client supporting **MCP Streamable HTTP**, enter the endpoint `http://127.0.0.1:3002/mcp` to fill.
After configuration, two MCP tools, `get_doc` and `execute_script`, will appear in the tool.
## Usage Tutorial
This service exposes two MCP tools to the outside, **the usage order is very important**:
### 1. Call `get_doc` first
`get_doc()` returns the complete game API manual (all available functions, examples, coding specifications).
**Before the first `execute_script`, you must call `get_doc` once** - otherwise `execute_script` will be intercepted and prompted to read the manual.
### 2. Call `execute_script`
`execute_script(code, timeout=120)` submits Python code to the game end for execution and is the only entry point for interacting with the game.
Supports two modes:
- **Synchronous mode** (no `yield` in the code): execute immediately and return information with `print()`.
- **Coroutine mode** (with `yield` in the code): define a generator function and use `yield` to wait for asynchronous operations
(navigation, block destruction, etc.). The game executes step by step and returns results after completion.
Parameters:
- `code` (string, required): Python code to be executed
- `timeout` (number, optional): maximum waiting seconds in coroutine mode, default `120`
Example - synchronous query:
```python
pos = get_position()
print("pos: %s" % str(pos))
inv = get_inventory()
print("inventory: %s" % str(inv))
```
Example - coroutine action (navigate and destroy block):
```python
def mine():
blocks = find_blocks("minecraft:grass_block", radius=16, max_results=1)
if not blocks:
print("no grass found")
return
bx, by, bz = blocks[0]["abs"]
yield navigate_to(bx, by, bz)
yield destroy_block(bx, by, bz)
print("done")
mine()
```
> For the complete API list, scene building specifications, and more examples, please call `get_doc` to obtain.
## Communication Protocol
TCP Socket is used with the game end, and the message format is **4-byte big-endian length header + JSON payload**.
Message types:
- `execute_script` → game end returns (including `coroutine_id`, polling required in coroutine mode)
- `poll_coroutine` → poll coroutine status (`running` / `completed` / `failed`)
- `heartbeat` → `heartbeat_ack` (every 10 seconds, to maintain connection)
