universal-host-manager-mcp

Universal Host Manager MCP

Um servidor multiplataforma Model Context Protocol para administrar um host Linux ou macOS por meio de clientes MCP, como ChatGPT e Claude.

Ele usa transporte HTTP Streamable do FastMCP, OAuth do Auth0, ferramentas de arquivo limitadas, limites de saída e timeouts de comando.

[!CAUTION] Este projeto expõe execução arbitrária de shell. A autenticação decide quem pode usá-lo; ela não torna os comandos inofensivos. Leia SECURITY.md antes de implantá-lo.

Recursos

• Suporte a Linux e macOS
• Endpoint HTTP Streamable
• Integração OAuth com Auth0
• Leituras, gravações e listagens de diretórios de arquivos restritas a MCP_WORKSPACE_DIR
• Timeouts de comando e truncamento de saída configuráveis
• Limites de tamanho de arquivo e fallback de decodificação
• Inicialização com falha fechada quando a autenticação não está configurada
• Serviços de exemplo para systemd e launchd

Ferramentas

Ferramenta	Parâmetros	Finalidade
run_command	command: str, timeout: int	Executa um comando de shell arbitrário com o workspace como diretório de trabalho
read_file	path: str	Lê um arquivo de texto dentro do workspace
write_file	path: str, content: str	Grava texto UTF-8 dentro do workspace
list_dir	path: str = "."	Lista um diretório dentro do workspace
system_metrics	nenhum	Relata informações de disco, memória e principais processos

O limite do workspace se aplica às ferramentas de arquivo. Ele não isola run_command; os comandos mantêm todas as permissões do usuário do SO do serviço.

Requisitos

• Python 3.10+
• Linux ou macOS
• Conta Auth0 para uso remoto
• Endpoint HTTPS para clientes MCP remotos

Instalação

PyPI (recomendado)

pip install universal-host-manager-mcp

uv / pipx

Sem poluir um ambiente de projeto:

uvx universal-host-manager-mcp

A partir do código-fonte (para desenvolvimento)

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

Configuração

Crie um arquivo .env (copie .env.example se você instalou a partir do código-fonte) com um workspace explicitamente restrito:

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 envie .env para o controle de versão.

Configuração do Auth0

Este projeto usa a integração OAuth de cliente fixo Auth0Provider do FastMCP.

1. No Auth0, crie uma API.
2. Use sua URL pública do MCP como identificador/audiência, por exemplo https://mcp.example.com/.
3. Crie um Regular Web Application.
4. Coloque o domínio, o client ID e o client secret em .env.
5. Adicione apenas as URLs de callback exigidas pelos seus clientes MCP às URLs de callback permitidas do aplicativo Auth0.
6. Defina as origens web permitidas e as URLs de logout do aplicativo conforme exigido pelos seus clientes.
7. Mantenha a assinatura RS256 habilitada.

O FastMCP também suporta um caminho MCP-nativo/DCR do Auth0 por meio de Auth0MCPProvider. Este repositório atualmente usa o caminho de cliente fixo gerenciado manualmente Auth0Provider.

Execução

universal-host-manager-mcp

(Executar a partir de um checkout do código-fonte com o .venv ativado funciona da mesma forma — o script de console é instalado por pip install -e ..)

Com a porta padrão, o endpoint HTTP Streamable é:

http://127.0.0.1:8765/mcp

Para um teste intencional apenas local, sem Auth0:

ALLOW_INSECURE_NO_AUTH=true universal-host-manager-mcp

Não use o modo inseguro em um endpoint acessível publicamente.

Cloudflare Tunnel

Instale o cloudflared, autentique-o e crie um túnel nomeado:

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

Crie ~/.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

Valide e execute:

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

Sua URL MCP remota será:

https://mcp.example.com/mcp

Defina MCP_BASE_URL=https://mcp.example.com; não inclua /mcp em MCP_BASE_URL.

Implantação no AWS EC2

Estas etapas implantam o servidor em uma instância EC2 e o expõem com segurança a clientes MCP remotos.

1. Inicie a instância

• AMI: Ubuntu 24.04 LTS (os comandos abaixo são para Ubuntu/apt; no Amazon Linux 2023, use sudo dnf install -y python3-pip)
• Tipo de instância: t3.micro/t3.small é suficiente para cargas de trabalho típicas de gerenciamento
• Grupo de segurança: permita entrada SSH (22) apenas do seu próprio IP. Nenhuma outra porta de entrada é necessária se você usar a opção Cloudflare Tunnel abaixo.

2. Instale o servidor

Conecte-se via SSH à instância e instale a partir do 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. Configuração

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

Mantenha HOST=127.0.0.1. O servidor nunca deve escutar diretamente na interface pública da instância — a exposição à internet é tratada inteiramente pelo túnel ou balanceador de carga descrito abaixo, não abrindo a porta da própria instância.

4. Rede: obtenha uma URL HTTPS para a instância

O OAuth do Auth0 exige HTTPS. Escolha uma opção:

Opção A — Cloudflare Tunnel (recomendado, sem porta de entrada necessária)

Execute as etapas da seção Cloudflare Tunnel acima, a partir da instância EC2. Como o túnel é uma conexão apenas de saída, você não precisa abrir nenhuma porta de entrada além do SSH, não precisa de um Elastic IP, e a instância pode até ficar em uma sub-rede privada atrás de um gateway NAT.

Opção B — Application Load Balancer com certificado ACM

• Solicite um certificado ACM para seu domínio e anexe-o a um ALB
• Crie um listener HTTPS (443) no ALB encaminhando para a PORT da instância
• Grupo de segurança na instância: permita entrada PORT apenas do grupo de segurança do ALB, nunca de 0.0.0.0/0
• Aponte seu DNS para o ALB e defina MCP_BASE_URL para esse hostname

5. Execute como um serviço systemd

Reutilize a unidade incluída (veja Serviço em segundo plano abaixo):

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. Elastic IP

Não é necessário para nenhuma das opções de rede. O Cloudflare Tunnel conecta-se de saída independentemente do endereço da instância, e um ALB registra alvos por ID da instância ou IP privado, então também não precisa de um. Adicione um Elastic IP apenas se algo mais na sua configuração depender de um IP público fixo para esta instância.

ChatGPT e Claude

Adicione a URL pública HTTP Streamable à configuração de MCP/conector do cliente:

https://mcp.example.com/mcp

Conclua o login do Auth0 quando o cliente abrir o fluxo de autorização. As telas de configuração exatas e as opções de conector suportadas podem mudar, então siga a documentação atual do cliente em vez de usar instruções legadas de SSE.

Vários clientes podem se conectar ao mesmo servidor HTTP em execução. Cada cliente autentica de forma independente; nenhum processo de servidor ou porta separada é necessário.

Serviço em segundo plano

Linux systemd

Copie e edite a unidade incluída:

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

O exemplo usa diretivas de endurecimento do systemd. Ajuste ReadWritePaths, ProtectHome, o usuário, caminhos e permissões para corresponder aos recursos que o servidor MCP realmente precisa.

macOS launchd

Edite os caminhos em examples/com.user.mcpmanager.plist, depois:

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

Configuração

Variável	Padrão	Descrição
HOST	127.0.0.1	Endereço de escuta
PORT	8765	Porta de escuta
MCP_BASE_URL	URL local	URL base pública do OAuth, sem /mcp
MCP_WORKSPACE_DIR	home do usuário	Limite para ferramentas de arquivo e diretório de trabalho de comandos
MAX_OUTPUT_CHARS	64000	Máximo de caracteres de saída de ferramenta retornados
DEFAULT_CMD_TIMEOUT	300	Timeout padrão de comando em segundos
MAX_CMD_TIMEOUT	1800	Timeout máximo aceito de comando
MAX_READ_BYTES	5000000	Tamanho máximo de arquivo lido por read_file
MAX_WRITE_BYTES	5000000	Tamanho máximo de conteúdo gravado por write_file
LOG_LEVEL	INFO	Nível de log do Python
ALLOW_INSECURE_NO_AUTH	false	Bypass explícito de autenticação para desenvolvimento local

Download

Clone com Git:

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

Ou use Code → Download ZIP no GitHub.

Licença

MIT