blockmine-mcp

English | Русский

Model Context Protocol bridge and setup wizard for BlockMine. The MCP server itself lives inside BlockMine — this package is a thin client that lets stdio-only AI clients (Claude Desktop, older Cursor/Cline) talk to it.

Architecture

                            Authorization: Bearer pk_...
  AI client ────HTTP MCP─────────────────────────────────► BlockMine /api/mcp
  (Claude Code, Cursor, Cline,
   Claude Desktop, ...)

           or, for stdio-only clients:

  AI client ──stdio──► blockmine-mcp (npm) ──HTTP MCP──► BlockMine /api/mcp

The MCP endpoint is part of BlockMine itself. You authenticate with a regular Panel API Key. You can connect from any host — local or remote — as long as BlockMine is reachable.

Quick start

npx blockmine-mcp setup

The wizard will:

1. ask for the BlockMine URL (auto-detects http://localhost:3001),
2. open the API Keys page so you can create a pk_... token,
3. verify the token,
4. register the server in your AI client of choice (Claude Code via CLI, Claude Desktop via config file, or just print a snippet you paste yourself).

Restart the AI client. Done.

Manual install

If you'd rather configure things by hand, pick the snippet for your client.

Native HTTP (recommended)

For clients that speak HTTP MCP — Claude Code, recent versions of Cursor and Claude Desktop:

Claude Code (CLI):

claude mcp add --scope user --transport http blockmine \
  http://localhost:3001/api/mcp \
  --header "Authorization: Bearer pk_your_key_here"

Config file format:

{
  "mcpServers": {
    "blockmine": {
      "type": "http",
      "url": "http://localhost:3001/api/mcp",
      "headers": { "Authorization": "Bearer pk_your_key_here" }
    }
  }
}

stdio fallback (via this wrapper)

For older clients that only support stdio (some Cline builds, Zed, etc.):

{
  "mcpServers": {
    "blockmine": {
      "command": "npx",
      "args": ["-y", "blockmine-mcp"],
      "env": {
        "BLOCKMINE_URL": "http://localhost:3001",
        "BLOCKMINE_API_TOKEN": "pk_your_key_here"
      }
    }
  }
}

Requirements

• Node.js 18 or newer.
• A running BlockMine reachable over HTTP.
• A Panel API Key (pk_...) created in BlockMine → Settings → API Keys.

Environment variables (proxy mode)

Variable	Default	Purpose
BLOCKMINE_URL	http://localhost:3001	Base URL of the BlockMine panel.
BLOCKMINE_API_TOKEN	(required)	Panel API Key.
BLOCKMINE_API_TIMEOUT_MS	30000	Per-request timeout.

Tools exposed by the BlockMine MCP server

Bot lifecycle: list_bots, get_bot, get_bot_states, start_bot, stop_bot, restart_bot, send_message_to_bot, get_bot_logs

Plugins: get_bot_plugins, get_plugin_settings, get_plugin_store, update_plugin_settings, enable_disable_plugin, install_local_plugin

Management: get_bot_users, get_user_info, get_bot_groups, get_bot_permissions, get_bot_commands

Permissions are enforced per tool using the same scopes BlockMine already uses for the panel API (bot:start_stop, plugin:settings:edit, management:view, etc.). The token's role determines which tools succeed.

Troubleshooting

Cannot reach BlockMine at ... — Panel offline or wrong URL. Start BlockMine and re-run setup.

401 / token did not authorise — Key wrong, expired or revoked. Generate a new one in the panel and re-run setup.

403 / permission denied — The token's role lacks the required scope. Edit the role in the panel or use a key with broader scopes.

License

MIT — see LICENSE.