universal-host-manager-mcp

Universal Host Manager MCP

Un servidor multiplataforma del Model Context Protocol para administrar un host Linux o macOS a través de clientes MCP como ChatGPT y Claude.

Utiliza el transporte HTTP Streamable de FastMCP, OAuth de Auth0, herramientas de archivos acotadas, límites de salida y tiempos de espera para comandos.

[!CAUTION] Este proyecto expone la ejecución arbitraria de comandos shell. La autenticación decide quién puede usarlo; no hace que los comandos sean inofensivos. Lea SECURITY.md antes de implementarlo.

Características

• Soporte para Linux y macOS
• Endpoint HTTP Streamable
• Integración con OAuth de Auth0
• Lecturas, escrituras y listados de directorios de archivos restringidos a MCP_WORKSPACE_DIR
• Tiempos de espera configurables para comandos y truncamiento de salida
• Límites de tamaño de archivo y respaldo de decodificación
• Inicio con cierre seguro cuando la autenticación no está configurada
• Servicios de ejemplo para systemd y launchd

Herramientas

Herramienta	Parámetros	Propósito
run_command	command: str, timeout: int	Ejecuta un comando shell arbitrario con el espacio de trabajo como directorio de trabajo
read_file	path: str	Lee un archivo de texto dentro del espacio de trabajo
write_file	path: str, content: str	Escribe texto UTF-8 dentro del espacio de trabajo
list_dir	path: str = "."	Lista un directorio dentro del espacio de trabajo
system_metrics	ninguno	Informa sobre disco, memoria e información de los procesos principales

El límite del espacio de trabajo se aplica a las herramientas de archivos. No aísla run_command; los comandos conservan todos los permisos del usuario del sistema operativo del servicio.

Requisitos

• Python 3.10+
• Linux o macOS
• Cuenta de Auth0 para uso remoto
• Endpoint HTTPS para clientes MCP remotos

Instalación

PyPI (recomendado)

pip install universal-host-manager-mcp

uv / pipx

Sin contaminar un entorno de proyecto:

uvx universal-host-manager-mcp

Desde el código fuente (para desarrollo)

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 .
cp .env.example .env

Configuración

Cree un archivo .env (copie .env.example si instaló desde el código fuente) con un espacio de trabajo explícitamente restringido:

HOST=127.0.0.1
PORT=8765
MCP_BASE_URL=https://mcp.example.com
MCP_WORKSPACE_DIR=/home/youruser/workspace

AUTH0_DOMAIN=your-tenant.eu.auth0.com
AUTH0_CLIENT_ID=replace_me
AUTH0_CLIENT_SECRET=replace_me
AUTH0_AUDIENCE=https://mcp.example.com/

Nunca confirme .env.

Configuración de Auth0

Este proyecto utiliza la integración OAuth de cliente fijo Auth0Provider de FastMCP.

1. En Auth0, cree una API.
2. Use su URL pública de MCP como identificador/audiencia, por ejemplo https://mcp.example.com/.
3. Cree una Aplicación Web Regular.
4. Coloque su dominio, ID de cliente y secreto de cliente en .env.
5. Agregue solo las URL de devolución de llamada requeridas por sus clientes MCP a las URL de devolución de llamada permitidas de la aplicación de Auth0.
6. Configure los orígenes web permitidos y las URL de cierre de sesión de la aplicación según lo requieran sus clientes.
7. Mantenga habilitada la firma RS256.

FastMCP también admite una ruta nativa de MCP/DCR de Auth0 a través de Auth0MCPProvider. Este repositorio actualmente utiliza la ruta de cliente fijo Auth0Provider administrada manualmente.

Ejecución

universal-host-manager-mcp

(Ejecutar desde una copia del código fuente con el .venv activado funciona de la misma manera: el script de consola se instala mediante pip install -e .).

Con el puerto predeterminado, el endpoint HTTP Streamable es:

http://127.0.0.1:8765/mcp

Para una prueba intencional solo local sin Auth0:

ALLOW_INSECURE_NO_AUTH=true universal-host-manager-mcp

No use el modo inseguro en un endpoint accesible públicamente.

Túnel de Cloudflare

Instale cloudflared, autentíquelo y cree un túnel con nombre:

cloudflared tunnel login
cloudflared tunnel create universal-host-manager-mcp
cloudflared tunnel route dns universal-host-manager-mcp mcp.example.com

Cree ~/.cloudflared/config.yml:

tunnel: YOUR_TUNNEL_ID
credentials-file: /home/youruser/.cloudflared/YOUR_TUNNEL_ID.json

ingress:
  - hostname: mcp.example.com
    service: http://127.0.0.1:8765
  - service: http_status:404

Valídelo y ejecútelo:

cloudflared tunnel ingress validate
cloudflared tunnel run universal-host-manager-mcp

Su URL remota de MCP será:

https://mcp.example.com/mcp

Establezca MCP_BASE_URL=https://mcp.example.com; no incluya /mcp en MCP_BASE_URL.

Implementación en AWS EC2

Estos pasos implementan el servidor en una instancia EC2 y lo exponen de manera segura a clientes MCP remotos.

1. Inicie la instancia

• AMI: Ubuntu 24.04 LTS (los comandos a continuación son para Ubuntu/apt; en Amazon Linux 2023 use sudo dnf install -y python3-pip en su lugar)
• Tipo de instancia: t3.micro/t3.small es suficiente para cargas de trabajo de administración típicas
• Grupo de seguridad: permita el tráfico entrante SSH (22) solo desde su propia IP. No se requiere ningún otro puerto entrante si usa la opción de Túnel de Cloudflare a continuación.

2. Instale el servidor

Conéctese por SSH a la instancia y luego instale desde PyPI:

sudo apt update && sudo apt install -y python3-pip python3-venv
python3 -m venv ~/uhm-venv
source ~/uhm-venv/bin/activate
pip install universal-host-manager-mcp

3. Configuración

mkdir -p ~/workspace
cat > ~/.env << 'EOF'
HOST=127.0.0.1
PORT=8765
MCP_BASE_URL=https://mcp.example.com
MCP_WORKSPACE_DIR=/home/ubuntu/workspace

AUTH0_DOMAIN=your-tenant.eu.auth0.com
AUTH0_CLIENT_ID=replace_me
AUTH0_CLIENT_SECRET=replace_me
AUTH0_AUDIENCE=https://mcp.example.com/
EOF
chmod 600 ~/.env

Mantenga HOST=127.0.0.1. El servidor nunca debe escuchar directamente en la interfaz pública de la instancia: la exposición a Internet se maneja completamente mediante el túnel o el balanceador de carga descrito a continuación, no abriendo el puerto propio de la instancia.

4. Red: obtenga una URL HTTPS para la instancia

El OAuth de Auth0 requiere HTTPS. Elija una opción:

Opción A — Túnel de Cloudflare (recomendado, sin puerto entrante necesario)

Ejecute los pasos de la sección Túnel de Cloudflare anterior, desde la instancia EC2. Debido a que el túnel es una conexión solo de salida, no necesita abrir ningún puerto entrante más allá de SSH, no necesita una IP elástica, y la instancia incluso puede estar en una subred privada detrás de una puerta de enlace NAT.

Opción B — Balanceador de carga de aplicación con certificado ACM

• Solicite un certificado ACM para su dominio y adjúntelo a un ALB
• Cree un listener HTTPS (443) en el ALB que reenvíe al PORT de la instancia
• Grupo de seguridad en la instancia: permita el tráfico entrante PORT solo desde el grupo de seguridad del ALB, nunca desde 0.0.0.0/0
• Apunte su DNS al ALB y establezca MCP_BASE_URL a ese nombre de host

5. Ejecute como un servicio systemd

Reutilice la unidad incluida (consulte Servicio en segundo plano a continuación):

sudo cp examples/mcp-manager.service /etc/systemd/system/
# edit User=, WorkingDirectory=, EnvironmentFile= and ExecStart= to point at
# ~/uhm-venv/bin/universal-host-manager-mcp and ~/.env
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-manager
sudo systemctl status mcp-manager --no-pager

6. IP elástica

No es necesaria para ninguna de las opciones de red. El Túnel de Cloudflare se conecta hacia afuera independientemente de la dirección de la instancia, y un ALB registra los objetivos por ID de instancia o IP privada, por lo que tampoco la necesita. Solo agregue una IP elástica si algo más en su configuración depende de una IP pública fija para esta instancia.

ChatGPT y Claude

Agregue la URL pública HTTP Streamable a la configuración de MCP/conector del cliente:

https://mcp.example.com/mcp

Complete el inicio de sesión de Auth0 cuando el cliente abra el flujo de autorización. Las pantallas de configuración exactas y las opciones de conector compatibles pueden cambiar, así que siga la documentación actual del cliente en lugar de usar instrucciones SSE heredadas.

Varios clientes pueden conectarse al mismo servidor HTTP en ejecución. Cada cliente se autentica de forma independiente; no se requiere un proceso de servidor ni un puerto separados.

Servicio en segundo plano

systemd en Linux

Copie y edite la unidad incluida:

sudo cp examples/mcp-manager.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now mcp-manager
sudo systemctl status mcp-manager --no-pager

El ejemplo utiliza directivas de endurecimiento de systemd. Ajuste ReadWritePaths, ProtectHome, el usuario, las rutas y los permisos para que coincidan con los recursos que el servidor MCP realmente necesita.

launchd en macOS

Edite las rutas en examples/com.user.mcpmanager.plist, luego:

cp examples/com.user.mcpmanager.plist ~/Library/LaunchAgents/
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.user.mcpmanager.plist
launchctl kickstart -k gui/$(id -u)/com.user.mcpmanager

Configuración

Variable	Predeterminado	Descripción
HOST	127.0.0.1	Dirección de escucha
PORT	8765	Puerto de escucha
MCP_BASE_URL	URL local	URL base pública de OAuth, sin /mcp
MCP_WORKSPACE_DIR	directorio de inicio del usuario	Límite para las herramientas de archivos y el directorio de trabajo de comandos
MAX_OUTPUT_CHARS	64000	Máximo de caracteres de salida de herramientas devueltos
DEFAULT_CMD_TIMEOUT	300	Tiempo de espera predeterminado de comandos en segundos
MAX_CMD_TIMEOUT	1800	Tiempo de espera máximo aceptado para comandos
MAX_READ_BYTES	5000000	Tamaño máximo de archivo leído por read_file
MAX_WRITE_BYTES	5000000	Tamaño máximo de contenido escrito por write_file
LOG_LEVEL	INFO	Nivel de registro de Python
ALLOW_INSECURE_NO_AUTH	false	Omisión explícita de autenticación para desarrollo local

Descarga

Clone con Git:

git clone https://github.com/Abktya/universal-host-manager-mcp.git

O use Code → Download ZIP en GitHub.

Licencia

MIT