SSH Alias Manager via MCP
leehom0123/ssh-alias-mcp
Configure servidores uma vez em YAML, deixe IA executar comandos SSH sem reescrita
Ver no GitHubServidor MCP que permite agentes IA (Claude, Cursor, Windsurf) gerenciar servidores Linux via SSH sem reescrever credenciais. Usa configuração YAML unificada com herança de aliases e gera ferramentas automáticas para executar comandos, deployar código e consultar logs.
Instalação
npx convez-ai leehom0123/ssh-alias-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar deployments e restarts de serviços via agentes IA
- Consultar logs e diagnosticar erros em produção interativamente
- Executar checagens de saúde (disk, memória, containers) sob demanda
- Reduzir token burn eliminando boilerplate de conexão SSH repetido
Veredito

Ferramenta prática e bem arquitetada para DevOps que elimina duplicação de configuração SSH entre CLI e agentes IA. Ideal para equipes que querem delegar troubleshooting a assistentes sem comprometer segurança ou reutilização de config.
README
A tradução para o português deste README ainda está na fila.
🚀 ssh-alias-mcp — Let Your AI Agent Manage Linux Servers
📖 Full Technical Docs (DOCS.md) — architecture, all config fields, MCP tools reference, script examples
Agent Setup in One Sentence
Read https://github.com/leehom0123/ssh-alias-mcp/blob/main/AI_INSTALL.md — set up the SKILL and install the MCP service as described.
What Is This?
A ~2,000-line Python tool that lets AI agents (Claude Code, Codex CLI, Cursor, Windsurf) SSH into your Linux servers, run commands, deploy code, tail logs, restart services. It also doubles as a nice CLI for day-to-day manual use.
One set of YAML config, one connection pool, works for both AI and humans.
Why I Built This
I do a lot of dev and ops work: deploying projects, checking logs, troubleshooting server crashes. Painful, honestly — every time it's open terminal, SSH in, type commands. One server is fine; bouncing between several gets old fast.
When AI agents started getting capable, I thought: why not let AI check my logs, analyze errors, deploy apps? But there was a problem — every time I asked AI to do something, it had to write out SSH connection details from scratch, burning through tokens fast. It hurt to watch.
I first wrote a Python script for AI to call. It worked, but it didn't feel clean enough. So I took it all the way — built this MCP + CLI tool: configure your servers in YAML once, AI and CLI both use it, AI never writes connection boilerplate again.
Open-sourcing in case other devs stuck in the ops trenches find it useful.
Get Started
📥 Installation: read AI_INSTALL.md — set up MCP and add SKILL.md as described. (You can also just paste the GitHub URL to your AI agent and let it install itself.)
| Tool | Description |
|---|---|
ssh_list_servers | List all configured servers |
ssh_run | Execute a command on a remote server |
ssh_run_sudo | Execute as root (requires sudo_password) |
ssh_upload_script | Upload a script, optionally run immediately |
ssh_run_script | Run an uploaded script |
ssh_run_alias | Run an alias-defined command |
ssh_alias:{server}:{name} | One-click alias, one MCP tool per alias |
⚠️ Don't inline
sudo -S— usessh_run_sudo. For docker permission issues, setsudo: truein the alias.
⌨️ CLI Mode
python cli.py list-servers # See all servers
python cli.py my-server run "uptime" # Run a command
python cli.py my-server sudo "apt update" # Run as root
python cli.py my-server alias healthcheck # Run an alias
python cli.py my-server upload script.sh -r # Upload & run immediately
🎯 Key Highlights
1. YAML Config Reuse + extends Inheritance
One server = one YAML file. Structure it like this:
servers/
├── _shared/common.yml # Shared aliases, inherited by all servers
├── prod-web-01.yml # Production server
├── prod-web-02.yml # Another production server
└── staging.yml # Staging
Define common checks and commands once in _shared/common.yml — every server extends it:
# _shared/common.yml
aliases:
- name: healthcheck
inline: "df -h / && free -h && uptime"
desc: "One-click health check"
- name: docker-ps
inline: "docker ps --format 'table {{.Names}}\t{{.Status}}'"
desc: "Running containers"
- name: logs-nginx
inline: "tail -50 /var/log/nginx/error.log"
desc: "Nginx error logs"
# prod-web-01.yml
extends:
- _shared/common.yml # Inherit shared aliases
server:
host: "198.51.100.10"
user: "deploy"
password: "xxx"
sudo_password: "xxx"
system: "Ubuntu 22.04 LTS"
aliases:
- name: deploy
script: deploy.sh
desc: "Deploy main site"
timeout: 600
sudo: true
- name: restart
inline: "systemctl restart my-app && echo 'restarted'"
desc: "Restart app"
sudo: true
5, 10, or 20 servers — same effortless maintenance. Same aliases work for AI and CLI. You never write anything twice.
2. Aliases Become MCP Tools Automatically
Define deploy in YAML, and your AI agent gets ssh_alias:prod-web-01:deploy. One line of YAML = one AI skill. To the agent, server operations feel like local function calls.
3. One Connection Pool, Shared by AI & Humans
AI Agent ──→ MCP Protocol ──→ ssh_client.py ──→ Remote Server
Terminal ──→ CLI ──────────────→ ssh_client.py ──→ Remote Server
Same SSH connection, same connection pool, same config. AI deploys something, then you verify with python cli.py — same logic underneath. No duplicate tools, no duplicate config.
4. Connection Pool + Proxy + Sudo
- Connection pool: SSH connections auto-reused with 60s keepalive — no repeated handshakes
- SOCKS5 proxy: Global or per-server, auto falls back to direct connect if proxy is down
- Sudo: configure
sudo_passwordonce, run root commands without interactive prompts
Who Is This For?
- 🧑💻 You manage multiple VPS instances and don't want to SSH into each one manually
- 👥 Small teams with no dedicated DevOps — let AI help with daily checks
- 🤖 You want your AI agent to actually do things, not just chat
Tech Stack
Pure Python. Dependencies: paramiko + pyyaml + pysocks. Under 2,000 lines. Easy to read and hack.
pip install -r requirements.txt
License & Feedback
MIT licensed. Use it however you want. A ⭐ means a lot to me.
Issues and PRs welcome — Chinese or English, both fine.