GuiaIA MCP Server
This server provides read-only, privacy-safe observability and planning for a Minecraft world — it never changes the world or executes gameplay actions.
Check world status (
guia_status): read sanitized status without revealing player names.View performance metrics (
guia_performance): read available metrics; missing data stays null rather than guessed.Diagnose performance (
guia_diagnose): interpret existing telemetry and propose safe next steps without applying fixes.Observe the world (
guia_world_observe): read a bounded, privacy-safe aggregate sample of one already-loaded chunk.Plan a mission (
guia_plan_gather): parse a short Spanish request (≤180 chars) into an explicit, non-executing plan.
All five tools are marked read-only, so no gameplay actions, world edits, or player-identifying data are exposed.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GuiaIA MCP Server Check Minecraft server status and diagnose why it might be lagging."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
💡 What is GuiaIA?
Unlike conventional chatbots that simulate game awareness or scripts that blindly spam server commands, GuiaIA is an authentic, verifiable AI companion that connects to your Minecraft Java world as a co-player.
Every action GuiaIA performs—from walking and gathering wood to complex crafting trees, schematic construction, and Pokémon battles—is strictly anchored in:
Real Game Physics: Zero unearned success. The bot only acknowledges success when inventory deltas or block states are confirmed by the server.
Zero-Trust Cryptographic Security: Multi-party Ed25519 action grants, replay-proof monotonic sequences, and single-use nonces prevent command tampering and desynchronization.
Durable Write-Ahead Logging (WAL): Crash-resilient file persistence with
fsyncensures that sudden disconnections never duplicate or lose resources.Priority 0 Emergency Interruption: Instantaneous, single-key bot halts that bypass network nonces to stop all motion, block destruction, and combat immediately.
Related MCP server: OpenClaw MCP bridge
🚦 Verified Capabilities (V1.1.0)
GuiaIA follows a strict Honest Taxonomy standard. We distinguish simulated tests from real game execution:
Subsystem / Capability | Status | Taxonomic Classification | Verified Working Behavior |
P0 Emergency Stop | 🟢 Production |
| Aborts movement, pathfinding, digging, and combat in-flight within a single game tick. |
Natural Language Companion | 🟢 Production |
| Follows, guides, navigates terrain, and interacts via typed conversational commands. |
Chained Tool Crafting DAG | 🟢 Production |
| Decomposes complex recipes (e.g. |
Blueprint Construction Engine | 🟢 Production |
| Places structures from NBT/JSON schematics with spatial collision checks, gravity validation, and WAL logging. |
Cobblemon Radar | 🟢 Production |
| Scans nearby Pokémon; species and levels strictly verified against server |
Cobblemon Poké Ball Capture | 🟢 Production |
| Verifies ball consumption, confirms party insertion with Brigadier commands, and handles ACK loss fail-closed. |
Cobblemon Wild Battles | 🟢 Production |
| Exchanges turn-based moves, tracks health, and safely executes P0 halts via authoritative |
PC Pokémon Storage | 🟢 Production |
| Deposits and withdraws Pokémon between party and PC boxes, backed by persistent JSON storage. |
Web Telemetry Dashboard | 🟢 Production |
| Real-time map, bot health, inventory viewer, P0 stop button, and PIN-authenticated REST API. |
Triple Authority Security | 🟢 Production |
| Ed25519 session identity bridge, 10s single-use operator grants, and anti-rollback monotonic sequence witness. |
Timing-Safe PIN Pairing | 🟢 Production |
| 6-digit ephemeral PIN pairing with |
⚡ Quickstart Guide
1. Prerequisites
Node.js: v20.x or v22.x LTS (Download)
Java: Adoptium Temurin OpenJDK 21 (Download)
Minecraft: Java Edition 1.21.1 (Vanilla or Fabric with Cobblemon 1.8.2)
2. Installation
Clone the repository and install the production dependencies:
git clone https://github.com/iagorobo24-hub/GuiaIA.git
cd GuiaIA/companion
npm ci3. Launching the Interactive Companion
Start the interactive TUI console:
npm start
# or: node src/cli_v1.jsDuring boot, GuiaIA displays your 6-digit Web Dashboard PIN:
╔══════════════════════════════════════════════════════════════╗
║ GuiaIA Companion V1.1 Console ║
║ Web Dashboard: http://localhost:3000 ║
║ Pairing PIN: 482910 (Valid for 5 minutes) ║
╚══════════════════════════════════════════════════════════════╝4. Accessing the Web Dashboard
Open your browser to http://localhost:3000:
Enter the 6-digit PIN shown in your console.
Monitor real-time bot position, health, inventory, and nearby entities.
Access the Priority 0 Emergency Stop button directly from your browser.
5. Running the Autonomous Real Minecraft Lab
GuiaIA includes a self-contained test runner that automatically spins up an isolated, disposable Minecraft 1.21.1 + Fabric + Cobblemon 1.8.2 server and executes all 7 end-to-end missions:
# From repository root:
python scripts/qa_v1_1_real_minecraft_server.py🧪 Comprehensive Verification & Test Suite
The entire codebase has been certified through an independent technical audit and adversarial stress testing:
Test Suite | Tests Run | Passed | Failed | Skipped | Status |
Security & Cryptography ( | 205 | 205 | 0 | 0 | 100% PASS |
Product & Mechanics ( | 166 | 165 | 0 | 1 (Teselia) | 100% PASS |
Product QA Matrix ( | 19 | 18 | 0 | 1 (Teselia) | 100% PASS |
Adversarial Security Stress ( | 32 | 32 | 0 | 0 | 100% PASS |
Adversarial Mechanics Stress ( | 50 | 50 | 0 | 0 | 100% PASS |
In-Game E2E Missions ( | 7 | 7 | 0 | 0 | 100% PASS |
Total Consolidated | 479 | 477 | 0 | 2 | 100% PASS |
Note on Skips: The 2 skipped cases correspond exclusively to the multi-host physical witness test on Chromebook Teselia (PID 11085), strictly respecting our mandatory environment isolation rules.
🏛️ System Architecture
GuiaIA operates across four cleanly decoupled layers:
graph LR
subgraph Client ["Operator Interfaces"]
TUI["Interactive CLI"]
WEB["Web Dashboard"]
end
subgraph Security ["Security Perimeter"]
GATE["Ed25519 Gate & PIN Pairing"]
WIT["Monotonic Witness"]
P0["P0 Instant Halt"]
end
subgraph Engine ["Companion Engine"]
DAG["Crafting DAG Planner"]
BLD["Blueprint Builder"]
COB["Cobblemon 1.8.2 Engine"]
WAL["fsync WAL Journal"]
end
subgraph World ["Game Runtime"]
BOT["Mineflayer Client"]
MC["Fabric 1.21.1 Server"]
end
Client --> Security
Security --> Engine
Engine --> WorldFor detailed specifications, see System Architecture Specification.
📖 Documentation Index
System Architecture: Comprehensive component breakdown, security model, and network protocols.
Project Evolution & History: The full story from Python MCP prototypes to V1.1.0 certified production.
Master Audit Report: The official 17-finding audit log, adversarial stress benchmarks, and forensic certification.
User Manual: Step-by-step player guide, command reference, and troubleshooting.
Roadmap: Project milestones, completed phases, and upcoming features.
Contributing Guide: How to set up your dev environment, submit PRs, and run test suites.
🤝 Contributing
We welcome pull requests, bug reports, and suggestions! Please read our Contributing Guide to understand our coding standards, fail-closed design principles, and test taxonomy.
📄 License
GuiaIA is licensed under the MIT License.
Minecraft is a trademark of Mojang Synergies AB. Cobblemon is an open-source mod. GuiaIA is an independent open-source project and is not affiliated with Mojang or Microsoft.
Available Tools
5 toolsguia_diagnoseDiagnose performance without changing worldBRead-only
Interpret existing telemetry and propose safe next steps; never applies fixes.
Inputs: no named parameters.
guia_performanceMinecraft performance snapshotBRead-only
Read available metrics; absent data stays null (never guessed).
Inputs: no named parameters.
guia_plan_gatherPropose a bounded companion missionARead-only
Parse a Spanish request into an explicit non-executing plan. No gameplay actions.
Inputs: message (required).
guia_statusMinecraft world statusARead-only
Read sanitized status; does not reveal player names or change the world.
Inputs: no named parameters.
guia_world_observeRead bounded Fabric world observationARead-only
Read a recent, privacy-safe aggregate sample of one already-loaded chunk; no player identities or world changes.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The tools are mostly distinct: diagnose interprets telemetry, performance reads metrics, status reads sanitized status, world_observe reads chunk samples, and plan_gather parses requests into plans. However, diagnose, performance, status, and world_observe all overlap as read-only observability tools, which could cause some confusion for an agent deciding which read tool to use.
All tools share the guia_ prefix, which provides some consistency. But the suffixes mix verbs, nouns, and verb_noun patterns (diagnose, performance, plan_gather, status, world_observe), making the naming convention only partially predictable.
Five tools is well-scoped for a read-only diagnostics and planning server. Each tool appears to have a specific role, and the set is neither too thin nor too heavy.
For a read-only server that explicitly avoids applying fixes or modifying the world, the surface covers diagnosis, performance metrics, status reading, world observation, and planning. Minor gaps might exist around discovering available telemetry sources or detailed metric queries, but the core lifecycle is covered.
Maintenance
Related MCP Connectors
Stateless MCP gateway and OTel span-streaming bridge for hosted MCP servers.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Ovanek MCP: Model Context Protocol server for Ovanek platform tools; writes are dry-run by default.
Related MCP Servers
- AlicenseAqualityCmaintenanceA read-only MCP server that exposes AI Disk Doctor Core's scan, model inventory, and history tools via local stdio, with no mutation or shell capabilities.4Apache 2.0
- AlicenseNot gradedqualityCmaintenanceExposes OpenClaw gateway tools to MCP clients like Claude Code and Codex, enabling local tool calls, file operations, and subagent session management through a stdio MCP server.406 npmMIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to query a live Factorio 2.0 world through bounded read-only operations covering spatial, inventory, resource, and diagnostic data over loopback RCON.1-
- AlicenseNot gradedqualityCmaintenanceEnables MCP-compatible AI clients to inspect Godot project and editor state, observe opted-in running scenes, manage processes, and apply permission-scoped guarded edits. It starts read-only and exposes additional capabilities only through explicit command-line flags.Apache 2.0