Universal Host Manager MCP server

Universal Host Manager MCP

<!-- mcp-name: io.github.Abktya/universal-host-manager-mcp -->

A cross-platform Model Context Protocol server for administering a Linux or macOS host through MCP clients such as ChatGPT and Claude.

It uses FastMCP Streamable HTTP transport, Auth0 OAuth, bounded file tools, output limits and command timeouts.

[!CAUTION]

This project exposes arbitrary shell execution. Authentication decides who may use it; it does not make commands harmless. Read SECURITY.md before deploying it.

Features

• Linux and macOS support
• Streamable HTTP endpoint
• Auth0 OAuth integration
• File reads, writes and directory listings constrained to MCPWORKSPACEDIR
• Configurable command timeouts and output truncation
• File-size limits and decoding fallback
• Fail-closed startup when authentication is not configured
• Example systemd and launchd services

Tools

The workspace boundary applies to the file tools. It does not sandbox run_command; commands retain all permissions of the service's OS user.

Requirements

• Python 3.10+
• Linux or macOS
• Auth0 account for remote use
• HTTPS endpoint for remote MCP clients

Install

PyPI (recommended)

pip install universal-host-manager-mcp

Next: run uhm-setup to generate your .env — see Configure below.

uv / pipx

Without polluting a project environment:

uvx --from universal-host-manager-mcp uhm-setup

This installs into a throwaway environment, runs the setup wizard, and writes .env in the current directory. From then on, run the server itself the same way: uvx universal-host-manager-mcp.

From source (for development)

git clone https://github.com/Abktya/universal-host-manager-mcp.git
cd universal-host-manager-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

Next: run uhm-setup to generate your .env — see Configure below.

Configure

The easiest way is the interactive setup wizard, installed alongside the server:

uhm-setup

Run it from the directory where you want to keep the configuration. The server must later be started from that same directory so it can find .env.

For a first test, choose 1 — Local-only test. Press Enter to accept the port 8765; the port prompt expects a number, not y or n. This mode:

• creates a separate workspace directory by default;
• listens only on 127.0.0.1, so other computers cannot connect;
• requires no domain, tunnel, or Auth0 account;
• enables unauthenticated access only for that local test.

The wizard also offers Cloudflare Tunnel, an ngrok static domain, and an existing HTTPS URL for remote use. Remote modes require Auth0 and will not write a misleading, unusable configuration if Auth0 is skipped. It validates domains and URLs, then writes .env with 600 permissions—backing up an existing file to .env.bak first.

If a virtual environment is active, install and run both commands through that environment:

Shortened. The full README is on GitHub.