Bifrost MCP
kchattx/bifrost-mcp
Interface MCP para administração remota via SSH persistente com segurança de primeira ordem
Ver no GitHubServidor MCP que fornece uma interface limpa para agentes de IA gerenciarem sessões SSH persistentes com servidores remotos. Implementa execução de comandos, gerenciamento de cache sudo, transferência SFTP e autenticação segura via Paramiko, sem expor credenciais ao agente.
Instalação
npx convez-ai kchattx/bifrost-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
- Automação de tarefas administrativas em servidores remotos via agentes IA
- Gerenciamento de sessões SSH interativas sem expor credenciais
- Transferência de arquivos e execução de comandos em ambientes containerizados
- Integração de agentes IA com infraestrutura remota (preparação para WinRM)
Veredito

Bifrost MCP é uma solução técnica sólida para conectar agentes IA a infraestrutura remota com segurança em primeiro plano. Recomendado para equipes de DevOps que precisam de automação remota controlada por IA, com ressalva de que requer Python 3.11+ e gestão manual de credenciais via gopass.
README
A tradução para o português deste README ainda está na fila.
Bifrost MCP
Bifrost MCP exposes an MCP server for managing persistent interactive SSH sessions. Codex, Hermes Agent, or another MCP client can install this project locally and use it over stdio through the bifrost-mcp entrypoint.
Bifrost MCP is an MCP server for bridging AI agents to persistent remote SSH sessions, with command execution, terminal interaction, sudo cache management, and SFTP file transfer. It uses Paramiko as its SSH client; it does not shell out to ssh, does not use sshpass, and does not assume access to host-mounted key files inside a container. Command execution is MCP-first and runs through the existing interactive shell session; exec_command is intentionally not implemented.
Bifrost MCP currently focuses on SSH-backed remote shells. Future versions are intended to extend the same MCP-first control plane to additional remote-management transports such as WinRM, while preserving the same safety model: server-side credential resolution, explicit session state, and no secret material returned to the agent.
Requirements
- Python 3.11 or newer
mcp[cli]paramikogopassCLI for credential storage
Local Installation
Install Bifrost MCP in the same operating-system environment that will run the MCP client. For example, if Codex or Hermes Agent runs inside WSL, create the venv in WSL and use WSL paths. If the client runs on Windows, create a Windows venv and use Windows paths.
WSL/Linux:
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e .
.venv/bin/bifrost-mcp --help
.venv/bin/python -m bifrost_mcp --help
Windows PowerShell:
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .
.\.venv\Scripts\bifrost-mcp.exe --help
.\.venv\Scripts\python.exe -m bifrost_mcp --help
Install In Codex
Register the local stdio server with Codex. Prefer the installed bifrost-mcp console script instead of python -m bifrost_mcp; it avoids CLI parsing problems with dash-prefixed Python arguments in some MCP registration commands.
WSL/Linux, using the WSL virtualenv:
codex mcp add bifrost -- /path/to/bifrost-mcp/.venv/bin/bifrost-mcp
Windows PowerShell, using the Windows virtualenv:
codex mcp add bifrost -- C:\path\to\bifrost-mcp\.venv\Scripts\bifrost-mcp.exe
You can also edit Codex's config file directly. Use the config file for the environment where Codex runs, for example ~/.codex/config.toml in WSL/Linux or %USERPROFILE%\.codex\config.toml on Windows:
[mcp_servers.bifrost]
command = "/path/to/bifrost-mcp/.venv/bin/bifrost-mcp"
args = []
Windows equivalent:
[mcp_servers.bifrost]
command = "C:\\path\\to\\bifrost-mcp\\.venv\\Scripts\\bifrost-mcp.exe"
args = []
Install In Hermes Agent
Hermes Agent has a native MCP client. Register Bifrost MCP as a stdio MCP server with the hermes mcp add command. Use the console script as the command and leave --args empty.
WSL/Linux, using the WSL virtualenv:
hermes mcp add bifrost \
--command /path/to/bifrost-mcp/.venv/bin/bifrost-mcp
Windows PowerShell, using the Windows virtualenv:
hermes mcp add bifrost `
--command C:\path\to\bifrost-mcp\.venv\Scripts\bifrost-mcp.exe
The hermes mcp add command connects immediately and prompts which discovered tools to enable. Accept all tools, or choose selectively.
Direct ~/.hermes/config.yaml equivalent:
mcp_servers:
bifrost:
command: "/path/to/bifrost-mcp/.venv/bin/bifrost-mcp"
args: []
Windows path equivalent, for a Hermes process running on Windows:
mcp_servers:
bifrost:
command: "C:\\path\\to\\bifrost-mcp\\.venv\\Scripts\\bifrost-mcp.exe"
args: []
Verify the Hermes MCP registration:
hermes mcp test bifrost
hermes mcp list
After adding or changing the MCP server, restart Hermes Agent or run /reload-mcp inside an active Hermes session. Bifrost MCP tools are exposed with Hermes' MCP prefix, for example:
mcp_bifrost_create_ssh_session
mcp_bifrost_run_command
Running The MCP Server Directly
Codex should use the default stdio transport:
bifrost-mcp --transport stdio
For MCP protocol debugging, the server also supports MCP HTTP transports:
bifrost-mcp --transport sse --host 127.0.0.1 --port 8000
bifrost-mcp --transport streamable-http --host 127.0.0.1 --port 8000
Session cleanup defaults to one hour of inactivity and can be configured with either:
BIFROST_MCP_SESSION_IDLE_TIMEOUT_SECONDS=1800 bifrost-mcp
bifrost-mcp --session-idle-timeout-seconds 1800
Credential Store Setup
Bifrost MCP requires gopass for SSH and sudo secrets. Secrets are managed out-of-band by the local user and are never accepted as normal MCP tool parameters.
Credential slugs are deterministic and safe to display:
<purpose>://<username>@<canonical-host>
Rules:
purposeissshorsudo.- Hosts are lowercase.
- Include
:<port>only for non-default SSH ports. - SSH credentials can have a password record, a key record, or both; key records are preferred automatically.
- Sudo credentials are password records only.
Examples:
ssh://admin@example-host
sudo://admin@example-host
ssh://deploy@example-host:2222
Credential CLI
Credentials are managed locally through CLI commands:
# Password record: prompts securely when run from a terminal
bifrost-mcp credential add ssh://admin@example-host --password
bifrost-mcp credential add sudo://admin@example-host --password
# Or read from piped stdin for scripts
printf '%s' 'ssh-password' | bifrost-mcp credential add ssh://admin@example-host --password
# Private key record under the same SSH slug
bifrost-mcp credential add ssh://admin@example-host --key ~/.ssh/id_ed25519
# Metadata only; never prints secrets
bifrost-mcp credential list --host example-host
bifrost-mcp credential show ssh://admin@example-host
# Remove one record type from an exact slug
bifrost-mcp credential remove ssh://admin@example-host --key
bifrost-mcp credential remove ssh://admin@example-host --password
credential add refuses to overwrite an existing record of the same type. Use credential remove first if rotation is intentional.
Available MCP Tools
list_credentials(host): lists non-secret user metadata for one host, grouped by username.create_ssh_session(host, username, port=22): opens a new interactive SSH session using storedssh://...credentials.send_input(session_id, text): sends raw text to an existing session.send_control(session_id, key): sends one ofctrl-c,ctrl-d,ctrl-z,enter, orescape.read_output(session_id, clear_buffer=True): reads buffered output from a session.wait_for_output(session_id, pattern, timeout, regex=True, clear_buffer=True): waits until buffered output matches a regex or literal.run_command(session_id, command, timeout=30): runs a command inside the existing interactive shell and waits for a sentinel.check_sudo_cache(session_id, timeout=10): runssudo -n -vto check whether sudo is already warm.warm_sudo_cache(session_id, timeout=10): derivessudo://<session-user>@<session-host>, sends the password server-side, and warms sudo withsudo -S ... -v.clear_sudo_cache(session_id, timeout=10): invalidates sudo timestamp state withsudo -k.upload_file(session_id, local_path, remote_path, create_parents=False): uploads one MCP-server-local file over SFTP without overwriting.download_file(session_id, remote_path, local_path, create_parents=False): downloads one remote file to an MCP-server-local destination file path without overwriting.resize_session(session_id, width, height): resizes the remote PTY.list_sessions(): returns active session metadata and idle time.close_ssh_session(session_id): closes a session and removes it from server state.
Credential-Backed SSH Flow
- Call
list_credentials(host). - If exactly one SSH user is available, use that username. If zero or multiple SSH users are returned, ask the human which login user to use; do not guess.
- Call
create_ssh_session(host, username, port=22). - Bifrost MCP derives
ssh://<username>@<canonical-host>internally, resolves gopass records exactly, prefers key auth if present, otherwise uses password auth, and returns only non-secret session metadata.
Agent-facing SSH session creation does not accept password, auth_mode, private_key, or private_key_passphrase.
Command Execution And Interaction
Use run_command for ordinary non-interactive shell commands. It runs in the current interactive shell session, preserving state like cd, exported variables, and activated virtual environments. If a timeout occurs, Bifrost MCP returns partial output and leaves the remote command running; use send_control(session_id, "ctrl-c") if interruption is appropriate.
Use send_input, wait_for_output, and send_control for prompts, installers, pagers, REPLs, and terminal programs.
Sudo Cache Warming Flow
- Optionally call
check_sudo_cache(session_id). - If sudo needs a password, call
warm_sudo_cache(session_id). - Bifrost MCP derives
sudo://<session-user>@<canonical-host>internally, retrieves the password server-side, and runs:
sudo -S -p '[bifrost-mcp sudo password] ' -v && printf '\n__BIFROST_MCP_SUDO_OK__\n' || printf '\n__BIFROST_MCP_SUDO_FAILED__\n'
This warms the sudo timestamp cache with sudo -v; it does not enter a root shell and does not return the sudo password.
File Transfer
local_path is local to the Bifrost MCP server process filesystem, not necessarily the chat client. V1 supports files only, not recursive directories.
Uploads and downloads refuse to overwrite destination files. Set create_parents=True to create missing destination parent directories; otherwise missing parents return structured errors.
upload_file(session_id, "/tmp/local.tgz", "/home/user/local.tgz", create_parents=False)
download_file(session_id, "/var/log/app.log", "/tmp/app.log", create_parents=True)
Host Key Handling
Bifrost MCP uses Paramiko host-key handling with an accept-new policy:
- first-seen hosts are added automatically
- changed host keys still fail
- known hosts are stored in a dedicated file under the runtime user's
~/.sshdirectory
Not Implemented In This Plan
The following features remain deferred by design: host allowlist, audit logging, command mediation/policy enforcement, broad policy subsystem, additional remote-management transports, and Paramiko exec_command.