rackmind-mcp

Model Context Protocol server that exposes RackMind's homelab and server-management capabilities to Claude Code and any MCP-compatible client.

rackmind-mcp is a fourth surface alongside the desktop app, the CLI, and the RAG server. It does not introduce a new engine — it reuses the same ServerClient (Proxmox API + SSH) that powers rackmind-cli, so configuration, encryption, and connection logic stay in one place.

Prerequisites

• Node.js >= 20

• A RackMind config at ~/.config/rackmind/config.json with at least one server profile. The easiest way to create one is with rackmind-cli:

  npx rackmind-cli connect myserver

Install and register with Claude Code

The recommended path (no global install required):

claude mcp add -s user rackmind -- npx -y rackmind-mcp

This registers rackmind as a user-scope MCP server so it is available in every Claude Code project. npx -y rackmind-mcp downloads and runs the latest version on demand.

To add it manually, drop the following into a project .mcp.json (or your user-level Claude Code MCP config):

{
    "mcpServers": {
        "rackmind": {
            "command": "npx",
            "args": ["-y", "rackmind-mcp"]
        }
    }
}

Start Claude Code in that directory and you can immediately call any registered tool (for example, ask Claude to "list my containers" or "show the status of container 102").

Optional: global install

If you prefer a globally installed binary:

npm install -g rackmind-mcp

Then reference it as "command": "rackmind-mcp" in your MCP config.

Pointing at a non-default server profile

Set RACKMIND_SERVER in the env block:

{
    "mcpServers": {
        "rackmind": {
            "command": "npx",
            "args": ["-y", "rackmind-mcp"],
            "env": { "RACKMIND_SERVER": "lab-2" }
        }
    }
}

Tools

Read-only (auto-approved by most MCP clients)

• list_containers, list_vms, get_server_info, scan_infrastructure
• get_container_config, get_container_logs, get_system_logs
• list_snapshots, get_metrics, get_resource_usage
• list_templates, get_network_info, list_servers
• get_task_status, wait_for_task

Destructive (annotated destructiveHint, gated by client confirmation)

• start_container, stop_container, restart_container
• exec_command, exec_command_on_container
• create_snapshot, restore_snapshot
• switch_server

Provisioning (destructive, return a Proxmox UPID — chain wait_for_task)

• create_container, delete_container
• create_from_template
• configure_firewall_rule — note: writes the firewall config but does not reload the firewall. If the rule does not take effect, run pve-firewall restart via exec_command.

Resources

• rackmind://server/status — live status of the active profile
• rackmind://containers — JSON inventory of containers and VMs

Environment variables

| Variable | Effect | | ----------------- | -------------------------------------------------------------------- | | RACKMIND_SERVER | Override the active server alias for the duration of the MCP process |

See .env.example for the canonical list.

Logging

stdout is reserved for the MCP transport. All logs go to stderr and to ~/.rackmind/logs/mcp.log.

Development

npm install
npm run dev       # run via tsx
npm run inspect   # launch MCP Inspector against the dev server
npm run check     # lint + format:check + type-check + tests

rackmind-mcp is part of the RackMind polyrepo. It depends on rackmind-cli for all Proxmox and SSH logic — see CLAUDE.md for cross-package rules and the org engineering standards.

License

Business Source License 1.1 — source-available, not Open Source.

You may use rackmind-mcp for any purpose, including production use, with one limitation: you may not offer it to third parties as a hosted, managed, or commercial service that competes with RackMind's offerings (rackmind.ai subscriptions). Personal use, internal company use, and Bring-Your-Own-Key (BYOK) usage with your own AI provider credentials are explicitly permitted without restriction.

Each released version converts to Apache License 2.0 four years after its public release date. For alternative licensing arrangements, contact [email protected].

Earlier versions (0.2.x and below) remain MIT-licensed.