Cross-platform FastMCP server for authenticated remote Linux/macOS host administration
Quick Install
Automated & IDE SetupCopy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.
One-click editor setup isn’t available for this listing yet — we don’t have a confirmed install command, and we’d rather show nothing than point your editor at the wrong package or host. Follow the project’s own setup instructions, linked above.
Manual Client & Custom JSON ConfigExpand JSON â–¾
No confirmed setup config for this listing yet. We only publish a config block when the install details come from the project itself — its README, its docs, or a verified owner. We haven’t found those for universal-host-manager-mcp, and we’d rather show nothing than a guess you’d paste into your client. Follow the project’s own setup instructions for the current steps.
Documentation Overview
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
MCP_WORKSPACE_DIR - 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
| Tool | Parameters | Purpose |
|---|---|---|
run_command | command: str, timeout: int | Runs an arbitrary shell command with the workspace as its working directory |
read_file | path: str | Reads a text file inside the workspace |
write_file | path: str, content: str | Writes UTF-8 text inside the workspace |
list_dir | path: str = "." | Lists a directory inside the workspace |
system_metrics | none | Reports disk, memory and top-process information |
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)
Next: run uhm-setup to generate your .env — see Configure below.
uv / pipx
Without polluting a project environment:
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)
Next: run uhm-setup to generate your .env — see Configure below.
Configure
The easiest way is the interactive setup wizard, installed alongside the server:
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
workspacedirectory 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:
To verify that the command belongs to the active environment on macOS/Linux:
The first two paths should normally point inside .venv/bin. If they point to /opt/homebrew/bin while a virtual environment is active, reinstall with python -m pip install universal-host-manager-mcp.
Prefer to do it by hand? Create a .env file (copy .env.example if you installed from source) with an explicitly restricted workspace:
Never commit .env.
Auth0 setup
This project uses FastMCP's Auth0Provider fixed-client OAuth integration.
-
Open auth0.com, create an account, and open the Auth0 Dashboard.
-
Go to Applications → APIs → Create API.
-
Use your public MCP URL as its Identifier (audience), for example
https://mcp.example.com/. Keep RS256 as the signing algorithm. -
Go to Applications → Applications → Create Application, enter a name, select Regular Web Application, and create it.
-
Set Application Ownership to First-party. Open Application > API Access, select the API you created, and enable User-delegated Access.
-
On Auth0's Integrate into your application page, click Copy above the
.envblock. The wizard can importAUTH0_DOMAIN,AUTH0_CLIENT_ID, andAUTH0_CLIENT_SECRETfrom your clipboard or from a pasted block. If Auth0 displaysMASKED, reveal and copy the real Client Secret from the application's Settings tab; masked secrets are rejected. -
Copy the API's Identifier into
AUTH0_AUDIENCEwhen the wizard asks for it. It is intentionally separate because Auth0's application.envblock does not contain the API audience. -
In the Auth0 application's Settings, use the MCP server's public origin (without
/mcp) as follows:Auth0 field Value Application Ownership First-party Application Type Regular Web Application Application Login URI Leave blank Allowed Callback URLs https://mcp.example.com/auth/callbackAllowed Logout URLs https://mcp.example.comAllowed Web Origins https://mcp.example.comAllowed Origins (CORS) https://mcp.example.comAllow Cross-Origin Authentication Off / disabled Cross-Origin Verification Fallback URL Leave blank API Identifier / Audience https://mcp.example.com/Signing Algorithm RS256 Application > API Access User-delegated Access enabled for the created API MCP endpoint (entered in the AI client, not Auth0) https://mcp.example.com/mcp -
Save the Auth0 application settings, then run the wizard. Never share the Client Secret or commit
.envto Git.
The callback above is FastMCP's fixed upstream callback. Do not put Claude, ChatGPT, or Grok callback URLs into Auth0: those products are downstream MCP clients and FastMCP validates their redirect URIs separately during MCP client registration. Connect each product to https://mcp.example.com/mcp.
Auth0's Python quickstart also shows AUTH0_SECRET, APP_BASE_URL, PORT, and sample Flask code. They belong to Auth0's standalone sample web application and are not used by this MCP server; the wizard safely ignores them when importing the copied block.
Client notes:
- ChatGPT supports MCP OAuth client registration with CIMD and DCR. The server allows
https://chatgpt.com/connector_platform_oauth_redirect; add the public/mcpendpoint in ChatGPT developer mode. - Claude custom connectors accept the public
/mcpendpoint and start OAuth when you connect. - Grok custom connectors accept a publicly reachable MCP server URL and complete any required authentication. Grok availability may depend on the current Grok plan and workspace controls.
FastMCP also supports an Auth0 MCP-native/DCR path through Auth0MCPProvider. This repository currently uses the manually managed, fixed-client Auth0Provider path.
Run
(Running from a source checkout with the .venv activated works the same way — the console script is installed by pip install -e ..)
With the default port, the Streamable HTTP endpoint is:
For an intentional local-only test without Auth0:
Do not use insecure mode on a publicly reachable endpoint.
After starting the server (and the tunnel for remote mode), verify it:
The server and tunnel must remain running; closing either makes a tunneled endpoint unavailable.
Cloudflare Tunnel
Install cloudflared, authenticate it and create a named tunnel:
Create ~/.cloudflared/config.yml:
Validate and run it:
Related MCP Servers
Reviews
No reviews yet — be the first to share how this listing worked for you.
Frequently Asked Questions about Universal Host Manager MCP
AllMCPs Directory Badge
Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.
Badge Style:
Live Dynamic SVG Preview
Markdown (GitHub README)
[](https://allmcps.com/mcp/universal-host-manager-mcp)HTML Embed
<a href="https://allmcps.com/mcp/universal-host-manager-mcp"><img src="https://allmcps.com/api/badge/universal-host-manager-mcp?style=directory" alt="Universal Host Manager MCP on AllMCPs" /></a>Technical Specs & Signals
CategoryDeveloper Tools
27Quality signal: Emerging · 27/100How this signal is calculated ▾
Server availabilityNot measured
Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.
Verified ownership8/20
Documentation & tools11/30
Adoption & activity1/15
Community engagement0/10
A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.
Own this project?
This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.
Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.
Claim & get free dofollowShare & Embed
Add our SVG badge (dark/light directory styles) or embeddable widget to your site.