mcpd (Node VM Management MCP Server)

mcpd is a lightweight Model Context Protocol (MCP) server written in Golang. It acts as a standard, secure entry point for AI agents (such as Claude, Gemini, or other host-level clients) to programmatically manage and configure Linux operating systems running inside virtual machines.

It is built using the official Model Context Protocol Go SDK, ensuring compliance with the latest MCP specification protocol versions (including the 2026-07-28 protocol iteration).

---

🚀 Key Features

• Official SDK Compliance: Built directly on top of github.com/modelcontextprotocol/go-sdk/mcp, natively exposing standardized transports, session life-cycles, and tool capability validation.
• HTTP / SSE Transport: Serves unencrypted plain HTTP by default on 127.0.0.1:8444. Designed to run behind a reverse proxy (e.g., Nginx, Caddy, Cloudflare Tunnel, or Envoy) where TLS is terminated.
• Token Authentication & Middleware: Protects endpoints using API keys. Support is built-in for key validation via X-API-Key headers, Authorization: Bearer headers, or fallback URL query parameters.
• Preservation of Unix Permissions: Automatically reads, stores, and restores original file permissions when writing or patching files in /etc, maintaining system security compliance.
• Smart Service Handling: Non-zero exits from systemctl queries (like stopped service states) are reported as standard text outputs rather than tool invocation failures.

---

🛠️ Expose MCP Tools

mcpd registers and exposes the following tools:

Package Management

manage_packages

• Description: Manages OS packages using standard package managers.
• Behavior: Auto-detects the system’s package manager (apt-get, dnf, yum, or pacman) or lets you manually override.
• Arguments:
  • action (string, enum: "install", "remove", "update", "upgrade") - The package action to perform.
  • packages (array of strings) - The list of packages (required for "install" and "remove").
  • package_manager (string, optional, enum: "auto", "apt-get", "dnf", "yum", "pacman") - Manual package manager selection.

User Management

manage_users

• Description: Adds or deletes system users and assigns access levels.
• Behavior: Creates home directories, sets login shells, assigns secondary groups, and securely sets plain passwords by piping to chpasswd (preventing cmdline credential leaks).
• Arguments:
  • action (string, enum: "add", "delete") - Action to perform.
  • username (string) - Name of the user.
  • password (string, optional) - Login password (only for "add").
  • groups (array of strings, optional) - Secondary groups to join (only for "add").
  • shell (string, optional) - Default login shell (defaults to /bin/bash).

Service Management

manage_services