Bridge Mcp

Bridge MCP

[](https://github.com/muchiny/bridge-mcp/actions/workflows/ci.yml) [](https://crates.io/crates/bridge-mcp) [](https://docs.rs/bridge-mcp) [](https://crates.io/crates/bridge-mcp) [](LICENSE) [](https://modelcontextprotocol.io)

A Rust MCP server for secure remote infrastructure management — 476 tools, 9 protocols.

Claude Code  ◄──JSON-RPC──►  Bridge MCP  ◄──9 protocols──►  Your Infrastructure

---

Table of Contents

• [Features](#features)
• [Hero Workflows](#hero-workflows)
• [Quick Start](#quick-start)
• [Architecture](#architecture)
• [Configuration](#configuration)
• [Tool Groups](#tool-groups)
• [MCP Prompts & Resources](#mcp-prompts--resources)
• [CLI Usage](#cli-usage)
• [Daemon Mode](#daemon-mode)
• [Troubleshooting](#troubleshooting)
• [Development](#development)
• [License](#license)

---

Features

• 476 tools, 77 groups — manage Linux, Windows, Docker, Kubernetes, Podman, AWX, databases, LDAP, network equipment, certificates, and more
• 9 protocol adapters — SSH, WinRM, PSRP (PowerShell Remoting), Telnet, K8s Exec, Serial, AWS SSM, Azure, GCP
• Security-first — command whitelist/blacklist, 63 secret-redaction patterns + entropy detection, tamper-proof session recording, opt-in MCP elicitation confirmation for destructive operations
• Auto-discovery — reads ~/.ssh/config automatically, merges with YAML config
• Smart output — server-side jq_filter / yq_filter / columns / limit, TSV mode (60-80% token savings), pagination via ssh_output_fetch, per-client size limits (see [Token-efficient output](#token-efficient-output))
• Progressive MCP discovery — three meta-tools (mcp_list_tool_groups, mcp_search_tools, mcp_describe_tool) let clients browse the registry on demand instead of loading all 476 schemas up front
• MCP Tasks support — every tool advertises taskSupport: "optional", enabling async cancellation and progress notifications for long-running operations
• CLI + MCP — all tools available as CLI commands (10-32x token savings) or via MCP JSON-RPC
• Daemon mode — Unix-socket transport for multi-client local usage; built-in WinRmPool (120 s TTL) and K8sExecPool (300 s TTL) amortize TLS handshakes across calls
• 8700+ tests — #![forbid(unsafe_code)], Rust 2024 edition, strict clippy

---

Hero Workflows

Four end-to-end recipes that show why this exists. Every command runs through one CLI binary; all 476 tools sit behind the same flag conventions (--jq, --columns, --limit, --output-format).

1. Diagnose a Linux service in 4 commands

bridge-mcp status                                       # check host reachability
bridge-mcp tool ssh_service_status host=web1 service=nginx
bridge-mcp tool ssh_service_logs   host=web1 service=nginx lines=200
bridge-mcp tool ssh_journal_query  host=web1 unit=nginx priority=err since="-1h"

Built-in validation rejects unknown hosts before any SSH bytes leave your machine; outputs are sanitized through 63 secret-redaction patterns + entropy detection.

2. Inspect Kubernetes with 80% fewer tokens

# Dump all pods → 50 KB JSON. Pipe through server-side jq → ~6 KB TSV.
bridge-mcp --jq '.items[] | [.metadata.name, .status.phase, .spec.nodeName]' \
  --output-format=tsv \
  tool ssh_k8s_get host=k8s resource=pods namespace=default

bridge-mcp tool ssh_k8s_describe host=k8s resource=pod name=api-7d-xyz namespace=default
bridge-mcp tool ssh_k8s_logs     host=k8s pod=api-7d-xyz container=app tail=100

Filtering happens server-side, before truncation — you never lose data to the output cap. Same pattern works for ssh_docker_inspect, ssh_helm_status, ssh_awx_*, etc.

3. Cross-platform: Windows + Linux from one CLI

# Linux host
bridge-mcp tool ssh_service_status   host=web1 service=postgres
# Windows host (WinRM/PSRP under the hood — no agent install on the target)
bridge-mcp tool ssh_win_service_status host=appsrv service=W3SVC
bridge-mcp tool ssh_iis_restart        host=appsrv name=DefaultAppPool
bridge-mcp tool ssh_win_event_query    host=appsrv log=System level=Error since="-1h"

13 Windows tool groups (services, events, AD, IIS, scheduled tasks, registry, Hyper-V, …) map cleanly onto the same ssh_* namespace, no protocol switch in your prompts.

4. Audited destructive ops with elicitation

# config.yaml
security:
  require_elicitation_on_destructive: true   # MCP elicitation/create before any destructive_hint:true tool
audit:
  enabled: true
  path: /var/log/bridge-mcp/audit.log        # absolute, or ~/… (expanded to $HOME)

Session recording (tamper-proof asciinema/JSON) is driven at runtime by the ssh_recording_* tools plus the MCP_RECORDING_KEY env var — not a config section.

bridge-mcp tool ssh_helm_rollback host=k8s release=api revision=7
# → MCP client (Claude Code etc.) shows a confirmation dialog before the call leaves the bridge.
# → Audit log records the prompt, args, sanitized stdout, exit code, duration.

The dispatcher distinguishes read_only vs mutating vs mutating_idempotent vs destructive per tool (audited via tests/annotation_audit.rs), so confirmations only fire when state actually changes.

---

Quick Start

1. Install

# Linux x86_64 (recommended)
curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-linux-x86_64.tar.gz | tar xz
sudo mv bridge-mcp /usr/local/bin/

Other platforms & methods

# Linux aarch64 (Raspberry Pi, ARM servers)
curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-linux-arm64.tar.gz | tar xz
sudo mv bridge-mcp /usr/local/bin/

# macOS (Apple Silicon)
curl -fsSL https://github.com/muchiny/bridge-mcp/releases/latest/download/bridge-mcp-macos-arm64.tar.gz | tar xz
sudo mv bridge-mcp /usr/local/bin/

# Docker
docker pull ghcr.io/muchiny/bridge-mcp:latest

# From source
git clone https://github.com/muchiny/bridge-mcp && cd bridge-mcp && make release

Claude Desktop (DXT): download the .dxt file from Releases and drag-and-drop into Claude Desktop.

> Claude Code plugin (one command). Install the plugin from the marketplace — it registers the /bridge-mcp:bridge and /bridge-mcp:discover skills, the MCP server, and a binary-bootstrap hook: > > ``bash > claude plugin marketplace add muchiny/bridge-mcp > claude plugin install bridge-mcp@muchiny > cargo install --git https://github.com/muchiny/bridge-mcp --features full # the binary the plugin drives > `` > > The skills auto-trigger when you mention a remote host, Docker, Kubernetes, services, logs, ports, etc.

2. Configure

mkdir -p ~/.config/bridge-mcp
cp config/config.example.yaml ~/.config/bridge-mcp/config.yaml
chmod 600 ~/.config/bridge-mcp/config.yaml   # required — the server rejects
                                             # group/other-readable config (it may hold secrets)

> The config may contain SSH keys, sudo passwords and tokens, so bridge-mcp > refuses to start if config.yaml is group- or world-accessible (max 0640). > A fresh cp usually lands at 0644 — run the chmod above.

Edit ~/.config/bridge-mcp/config.yaml with your hosts:

hosts:
  my-server:
    hostname: 192.168.1.100
    port: 22
    user: admin
    auth:
      type: key
      path: ~/.ssh/id_ed25519
    description: "My server"

> Tip: Hosts from ~/.ssh/config are auto-discovered — you may not need to configure anything.

Recommended safe defaults — add these so Claude confirms before anything irreversible and every action is logged:

security:
  mode: standard                             # blacklist + whitelist for ssh_exec
  require_elicitation_on_destructive: true   # confirm before any destructive tool runs
audit:
  enabled: true
  path: ~/.local/share/bridge-mcp/audit.log  # ~ expands to $HOME; absolute paths also fine

Only the 8 core tool groups are enabled by default (secure-by-default) — opt into the rest under tool_groups (see [Tool Groups](#tool-groups); the example config ships ready-to-use K3s and Docker profiles).

3. Add to Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "ssh-bridge": {
      "command": "bridge-mcp"
    }
  }
}

4. Verify

Restart Claude Code, then ask: "Check the health of my-server" — or run:

bridge-mcp status

---

Architecture

Bridge MCP sits between Claude Code and your infrastructure. It routes commands through 9 protocol adapters with built-in security validation, output sanitization, and audit logging.

graph LR
    CC[Claude Code] -->|JSON-RPC stdio or Unix socket| BR[Bridge MCP]

    BR --> SEC[SecurityValidator · Sanitizer · Audit]
    SEC --> ER[Executor Router]

    subgraph "Air-Gapped Protocols"
        ER -->|SSH| P1[Linux / WindowsDocker · K8s · Network]
        ER -->|WinRM| P2[Windows]
        ER -->|PSRP| P2b[PowerShell Remoting]
        ER -->|Telnet| P3[Legacy Devices]
    end

    subgraph "Infrastructure Protocols"
        ER -->|K8s API| P6[K8s Exec]
        ER -->|Serial| P7[Serial Devices]
    end

    subgraph "Cloud Protocols"
        ER -->|SSM · Azure · GCP| P9[Cloud Instances]
    end

---

Configuration

Config file: ~/.config/bridge-mcp/config.yaml — see [config.example.yaml](config/config.example.yaml) for full reference.

Authentication methods

| Method | Config | Notes | |--------|--------|-------| | SSH Key | type: key + path: ~/.ssh/id_ed25519 | Recommended. Supports optional passphrase. | | SSH Agent | type: agent | Uses SSH_AUTH_SOCK. Recommended. | | Password | type: password + password: "..." | Avoid if possible. |

Verify your SSH access first: ssh user@hostname "echo OK"

Security rules

Three modes control which commands Claude can run:

| Mode | Behavior | |------|----------| | strict | Only whitelisted commands allowed (safest) | | standard | Whitelist for ssh_exec, built-in tools only check blacklist (default) | | permissive | Only blacklist checked (most open) |

The blacklist is always checked first — matched commands are always denied.

security:
  mode: standard
  whitelist:
    - "^docker\\s+(ps|logs|inspect).*"
    - "^kubectl\\s+(get|describe|logs).*"
    - "^(ls|cat|head|tail|grep|df|free)\\s*.*"
  blacklist:
    - "rm\\s+(-[a-zA-Z]*r|--(recursive|force))"
    - "mkfs\\."
    - "dd\\s+if="
    - "curl.*\\|.*sh"

Advanced hosts (jump hosts, SOCKS proxy, Windows, sudo)

Jump hosts (bastion):

hosts:
  bastion:
    hostname: bastion.example.com
    user: admin
    auth: { type: agent }

  internal-db:
    hostname: 10.0.0.5
    proxy_jump: bastion
    user: deploy
    auth: { type: key, path: ~/.ssh/id_ed25519 }

SOCKS proxy:

hosts:
  behind-proxy:
    hostname: 10.0.0.50
    user: deploy
    socks_proxy:
      hostname: proxy.corp.com
      port: 1080
      version: socks5
    auth: { type: key, path: ~/.ssh/id_ed25519 }

> proxy_jump and socks_proxy are mutually exclusive on the same host.

Windows servers — set os_type: windows so tools use Windows/PowerShell command semantics (the 74 Windows-specific tools live in the 13 Windows groups; enable them under tool_groups like any other group):

hosts:
  windows-dc:
    hostname: 192.168.1.200
    user: Administrator
    os_type: windows
    shell: powershell
    auth: { type: key, path: ~/.ssh/id_ed25519 }

Sudo support:

hosts:
  prod-server:
    hostname: 192.168.1.100
    user: deploy
    sudo_password: "your-sudo-password"
    auth: { type: key, path: ~/.ssh/id_ed25519 }

SSH config auto-discovery — hosts from ~/.ssh/config are merged automatically. To exclude specific hosts:

ssh_config:
  enabled: true
  exclude: [personal-server]

Limits, sanitization & audit

Limits:

limits:
  command_timeout_seconds: 60
  connection_timeout_seconds: 10
  max_concurrent_commands: 5
  max_output_chars: 20000          # 0 = unlimited
  rate_limit_per_second: 0         # 0 = disabled
  retry_attempts: 3
  client_overrides:                # Per-client output limits
    - name_contains: claude
      max_output_chars: 80000

Truncated outputs include an output_id — use ssh_output_fetch to retrieve the full content page by page.

Output sanitization — 63 built-in regex patterns + Shannon entropy detection for secrets:

security:
  sanitize:
    enabled: true
    entropy_detection: true
    entropy_threshold: 4.5
    custom_patterns:
      - pattern: "INTERNAL_[A-Z0-9]{32}"
        replacement: "[INTERNAL_REDACTED]"

Destructive-op confirmation — opt-in gate that asks the user to confirm via MCP elicitation/create before any tool annotated destructive_hint: true (ssh_terraform_apply, ssh_k8s_delete, ssh_cron_remove, ssh_win_update_reboot, …) executes. Requires a client that advertises the elicitation capability (Claude Desktop, Claude Code):

security:
  require_elicitation_on_destructive: true  # default: false

Audit logging:

audit:
  enabled: true
  path: ~/.local/share/bridge-mcp/audit.log
  max_size_mb: 100
  retain_days: 30

Session recording — asciinema v2 format with HMAC-SHA256 hash-chain (SOC2, HIPAA, PCI-DSS). This is not a YAML config section (the schema rejects unknown keys); it is driven at runtime by the ssh_recording_* tools (enable the recording tool group) with the HMAC key supplied via the MCP_RECORDING_KEY environment variable. Recordings are written as .cast files.

---

Tool Groups

476 tools organized in 77 groups. Secure by default: only the eight core groups (core, file_ops, directory, process, monitoring, network, systemd, sessions) are enabled out of the box — everything else (containers, K8s, Windows, cloud, …) is opt-in. Enable the groups you need, or disable defaults:

tool_groups:
  groups:
    docker: true       # opt in to a non-default group
    kubernetes: true
    sessions: false    # opt out of a default group

Linux & cross-platform groups (43 groups)

Representative tools per group — larger groups (e.g. kubernetes has 83, awx 43) list only the common ones. For the full set of any group, run bridge-mcp list-tools --group .

| Group | Tools | |-------|-------| | core | sshexec, sshexecmulti (with diff / diff_baseline / normalize for cross-host drift detection), sshstatus, sshhealth, sshhistory, sshoutputfetch | | config | sshconfigget, sshconfigset | | file_transfer | sshupload, sshdownload, sshsync | | file_ops | sshfileread, sshfilewrite, sshfileswrite, sshfilechmod, sshfilechown, sshfilestat, sshfilediff, sshfilepatch, sshfiletemplate | | sessions | sshsessioncreate, sshsessionexec, sshsessionlist, sshsessionclose | | monitoring | sshmetrics, sshmetricsmulti, sshtail, sshdiskusage | | tunnels | sshtunnelcreate, sshtunnellist, sshtunnelclose | | directory | sshls, sshfind | | database | sshdbquery, sshdbdump, sshdbrestore | | redis | sshredisinfo, sshrediscli, sshrediskeys | | postgresql | sshpostgresqlquery, sshpostgresqlstatus | | mysql | sshmysqlquery, sshmysqlstatus | | mongodb | sshmongodbstatus | | backup | sshbackupcreate, sshbackuplist, sshbackuprestore, sshbackupsnapshot, sshbackupverify, sshbackupschedule | | docker | sshdockerps, sshdockerlogs, sshdockerinspect, sshdockerexec, sshdockercompose, sshdockerimages, sshdockerstats, sshdockervolumels, sshdockernetworkls, sshdockervolumeinspect, sshdockernetworkinspect | | podman | sshpodmanps, sshpodmanlogs, sshpodmaninspect, sshpodmanexec, sshpodmanimages, sshpodmancompose | | esxi | sshesxivmlist, sshesxivminfo, sshesxivmpower, ssh

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: muchiny
• Source: muchiny/bridge-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.