<div align="center">

⛏️ Minehut MCP

Let any AI agent fully manage your Minehut Minecraft server.

Works with Claude Code, Codex, opencode, Cursor, Hermes and any other MCP client.

</div>

---

What it does

Two complementary layers, one install:

Layer	Tools	What the AI can do
🖥️ Browser automation (Playwright)	browser_open, browser_click, browser_type, browser_press, browser_text, browser_screenshot, browser_evaluate, browser_login_panel, browser_wait_manual, browser_close	Drive the real Minehut dashboard like a human. Handles Cloudflare, the login form, and every UI feature: plugins, players, world settings, files, billing, skins. This is the "do everything" layer.
⚡ Minehut API (REST)	minehut_servers, minehut_status, minehut_start, minehut_stop, minehut_restart, minehut_command, minehut_logs, minehut_upgrade_ram	Fast, scriptable control. Start/stop servers, send console commands (say, give, LuckPerms, etc.), read logs, check players.

Plus minehut_help for an in-server guide.

🚀 Install

Full documentation: https://tobralla.github.io/minehut-mcp/

One-time setup on your machine:

# 1. Install globally (any package manager works)
npm install -g github:Tobralla/minehut-mcp

# 2. Install Chromium for the browser layer
minehut-mcp-setup

For local development:

git clone https://github.com/Tobralla/minehut-mcp.git
cd minehut-mcp
npm install
npm run dev

Environment variables (optional)

Variable	Purpose
MINEHUT_EMAIL / MINEHUT_PASSWORD	Used by browser_login_panel when credentials are not passed per call
MINEHUT_TOKEN / MINEHUT_SESSION_ID	Direct API session (captured automatically after browser login)
MINEHUT_HEADLESS=0	Run the browser visibly (recommended for the first login, Cloudflare is friendlier with a visible window)

🔑 First-time login

1. Ask your AI to run browser_login_panel with your Minehut email and password.
2. A browser opens the dashboard and fills the login form.
3. A Cloudflare challenge or 2FA may appear. Run browser_wait_manual so you can finish it by hand.
4. The session token is captured automatically and stored in ~/.minehut-mcp/session.json (permissions 600). All minehut_* API tools become active.

Set MINEHUT_HEADLESS=0 in the client config below for a visible browser window on first login.

🔌 Client setup

Claude Code

claude mcp add minehut-mcp \
  --env MINEHUT_EMAIL=you@example.com \
  --env MINEHUT_PASSWORD='your password' \
  -- npx -y github:Tobralla/minehut-mcp

Codex (OpenAI)

codex mcp add minehut-mcp \
  --env MINEHUT_EMAIL=you@example.com \
  --env MINEHUT_PASSWORD='your password' \
  -- npx -y github:Tobralla/minehut-mcp

opencode

Add to opencode.json in your project, or ~/.config/opencode/opencode.json for all projects:

{
  "mcp": {
    "minehut": {
      "type": "local",
      "command": ["npx", "-y", "github:Tobralla/minehut-mcp"],
      "enabled": true,
      "environment": {
        "MINEHUT_EMAIL": "you@example.com",
        "MINEHUT_PASSWORD": "your password"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project (or use Settings > MCP):

{
  "mcpServers": {
    "minehut": {
      "command": "npx",
      "args": ["-y", "github:Tobralla/minehut-mcp"],
      "env": {
        "MINEHUT_EMAIL": "you@example.com",
        "MINEHUT_PASSWORD": "your password"
      }
    }
  }
}

Hermes

Add to hermes.toml (or config.toml):

[mcp.servers.minehut]
command = "npx"
args = ["-y", "github:Tobralla/minehut-mcp"]
env = { MINEHUT_EMAIL = "you@example.com", MINEHUT_PASSWORD = "your password" }

🛠️ Full tool list

Tool	Description
minehut_status <server>	Status, players, RAM, MOTD, version, plugins
minehut_servers	List all servers on the account
minehut_start <server>	Power on the server
minehut_stop <server>	Power off the server
minehut_restart <server>	Restart the server
minehut_command <server> <command>	Send a console command (operator privileges)
minehut_logs <server> [lines]	Read recent console output
minehut_upgrade_ram <server> <gb>	Change RAM allocation
browser_open [url]	Open the dashboard and read the page
browser_login_panel [email] [password]	Log in and capture the API session
browser_wait_manual [seconds]	Wait for a manual challenge/2FA, then capture the session
browser_click <selector>	Click an element
browser_type <selector> <text> [enter]	Type into an element
browser_press <key>	Send a keyboard key
browser_text [selector]	Read visible text of the page or an element
browser_screenshot [selector]	Screenshot the page as an image the AI can see
browser_evaluate <js>	Run JavaScript in the dashboard page
browser_close	Close the browser

⚠️ Safety notes

• Console commands run with operator privileges. Review what you ask the AI to run.
• The session token grants full control of your Minehut account. It is stored locally, but treat it like a password.
• Never paste credentials into a shared or public chat.
• Destructive actions (server reset, account deletion) are intentionally not automated by default. Use the browser tools and your own judgement.

📄 License

MIT. Not affiliated with Minehut or Mojang.