Gtnh MCP Game Chat

GTNH MCP Game Chat

An MCP (Model Context Protocol) server that bridges AI agents into Minecraft GTNH chat via the Scribe mod. The agent appears as a player — it reads chat messages, responds, writes books, and can control the game through a local HTTP API.

Cross-platform — the MCP server is pure Python (Windows, macOS, Linux). The Scribe mod is pure Java (anywhere Forge runs). Works with any MCP-compatible agent: Claude, Codex, OpenClaw, Pi-agent, etc.

Architecture

┌──────────────────────┐     MCP (stdio)      ┌──────────────────────┐
│   AI Agent            │ ◄─────────────────► │  gtnh_chat_mcp.py    │
│   (Claude, Codex,     │                      │  (Python MCP server) │
│    OpenClaw, Pi-agent,│                      └──────────┬───────────┘
│    etc.)              │                                 │
└──────────────────────┘                          HTTP (localhost:25566)
                                                         │
                                              ┌──────────▼───────────┐
                                              │  Scribe mod          │
                                              │  (Forge 1.7.10)      │
                                              │                      │
                                              │  Chat capture        │
                                              │  Player state        │
                                              │  Block scanning      │
                                              │  Written books       │
                                              │  Actions (chat,      │
                                              │   click, teleport)   │
                                              └──────────┬───────────┘
                                                         │
                                              ┌──────────▼───────────┐
                                              │  Minecraft 1.7.10    │
                                              │  + GTNH + Forge      │
                                              └──────────────────────┘

MCP Tools

The Book Pattern

Minecraft chat is limited to ~100 characters. Scribe uses written books for verbose output:

• Chat: brief acknowledgments ("On it.", "Report ready — check your inventory.")
• Books: full reports — ore surveys, inventory dumps, quest summaries, base layouts

Books appear in your inventory. Right-click to read. If inventory is full, they drop at your feet.

In-Game Guide Book

When you install the Scribe mod and join a world, a "Scribe Agent Guide" book appears in your inventory automatically. It covers commands, actions, scanning, inventory, books, tips, and examples.

If you lose it, type /scribe guide in chat to get a fresh copy. Anyone can use this command.

Quick Start

1. Build and install the mod

cd scribe-mod
./gradlew build
# Copy build/libs/scribe-1.1.0.jar into your GTNH instance's mods/ folder

Requires JDK 17+ and Gradle 7.6+ (uses RetroFuturaGradle for 1.7.10 targeting).

2. Install the MCP Python package

pip install mcp

3. Configure your agent

Hermes Agent (~/.hermes/config.yaml):

mcp_servers:
  gtnh:
    command: "python"
    args:
      - "/path/to/gtnh-mcp-game-chat/mcp-server/gtnh_chat_mcp.py"
    env:
      GTNH_MCP_BASE_URL: "http://127.0.0.1:25566"
    timeout: 30

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "gtnh": {
      "command": "python",
      "args": ["/path/to/gtnh_chat_mcp.py"],
      "env": {
        "GTNH_MCP_BASE_URL": "http://127.0.0.1:25566"
      }
    }
  }
}

Codex / OpenClaw / Pi-agent — same pattern: command: python, args: [script path], env: GTNH_MCP_BASE_URL.

4. Launch Minecraft

Start GTNH through Prism Launcher. Load a world. The Scribe API starts on localhost:25566. You'll get the guide book automatically.

5. Restart your agent

The MCP server connects on startup. Tools appear with the gtnh_ prefix.

How the agent uses it

Agent loop:
  1. gtnh_chat_read    → see what players are saying
  2. gtnh_chat_send    → brief ack in chat
  3. gtnh_player_status → check position, health
  4. gtnh_inventory    → check what you're carrying
  5. gtnh_scan_blocks  → survey the area
  6. gtnh_write_book   → full report as a readable book
  7. gtnh_teleport     → move to a location
  8. gtnh_click_block  → interact with a machine or chest

Project Structure

gtnh-mcp-game-chat/
├── README.md
├── scribe-mod/                     # Forge 1.7.10 mod
│   ├── build.gradle
│   ├── gradlew / gradlew.bat
│   └── src/main/java/com/scribe/scribemod/
│       ├── ScribeMod.java          # @Mod entry point + /scribe guide command
│       ├── ApiServer.java          # HTTP server + chat endpoints
│       ├── GuideBook.java          # Auto-given instruction book
│       ├── chat/
│       │   └── ChatListener.java   # Forge event bus chat capture
│       └── api/
│           ├── PlayerHandler.java  # /player, /inventory, /nearby
│           ├── WorldHandler.java   # /world/block, /world/blocks
│           ├── ActionHandler.java  # /action/chat, /click, /move
│           └── BookHandler.java    # /action/book — written books
└── mcp-server/
    └── gtnh_chat_mcp.py            # MCP stdio server (9 tools)

Environment Variables

Cross-Platform Notes

• Windows: Prism instances at %APPDATA%\PrismLauncher\instances\
• macOS: Prism instances at ~/Library/Application Support/PrismLauncher/instances/
• Linux: Prism instances at ~/.local/share/PrismLauncher/instances/
• The mod jar is identical on all platforms
• The MCP server script is identical on all platforms

Requirements

• Minecraft: GTNH 2.8+ (1.7.10 Forge) via Prism Launcher
• Java: JDK 17+ (for building the mod; GTNH itself runs on Java 17-25)
• Python: 3.8+ with pip install mcp
• Network: localhost access (the API binds to 127.0.0.1 only)

Security

• Scribe binds to 127.0.0.1 only — not accessible from the network
• Optional bearer token auth via mod config
• Action endpoints (chat send, click, teleport, book) can be disabled entirely
• MCP server runs as a local subprocess — no network exposure

License

MIT

Autonomous Chat Companion (Agent Setup Guide)

For AI agents reading this: The user may want an always-on companion that monitors chat and responds automatically. This requires setting up a cron job in their Hermes configuration.

When to suggest this:

• User asks about "always-on" or "automatic" chat responses
• User wants the agent to reply without manual triggers
• User asks about "scheduling" or "monitoring" chat

What to offer:

Basic Chat Companion (no web search)

hermes cron create \
  --name "GTNH Chat Companion" \
  --schedule "every 1m" \
  --deliver origin \
  --skills minecraft-agent-toolset \
  --prompt "You are a GTNH companion agent running as a cron job. Every tick, check Minecraft chat and respond to players. Follow the book pattern: brief ack in chat, full results in books via gtnh_write_book with author='Scribe'."

Enhanced Companion (with GTNH wiki search)

Offer this when: User asks recipe questions, "how do I make X", or mentions being stuck on progression.

First create the job, then update it:

hermes cron create \
  --name "GTNH Chat Companion" \
  --schedule "every 1m" \
  --deliver origin \
  --skills minecraft-agent-toolset \
  --prompt "You are a GTNH companion agent with web access. Check chat, respond to questions. For GTNH mechanics/recipes, use web_search to find current info. Follow book pattern for verbose output."

# Then enable web search:
hermes cron update GTNH_CHAT_JOB_ID --enabled-toolsets minecraft-agent-toolset,web

Note: Replace GTNH_CHAT_JOB_ID with the actual job ID returned from create.

Schedule Options

• "every 1m" — good for chat (default)
• "every 30s" — faster responses, more tokens
• "every 2m" — slower, more token-efficient