# Bridge Mcp

> MCP server for secure SSH remote management — 337 tools across 74 groups for DevOps, Docker, Kubernetes, databases, systemd, Windows, cloud, compliance & more. Built in Rust.

- **Type:** MCP server
- **Install:** `agentstack add mcp-muchiny-bridge-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [muchiny](https://agentstack.voostack.com/s/muchiny)
- **Installs:** 0
- **Category:** [Cloud & Infrastructure](https://agentstack.voostack.com/c/cloud-infrastructure)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [muchiny](https://github.com/muchiny)
- **Source:** https://github.com/muchiny/bridge-mcp

## Install

```sh
agentstack add mcp-muchiny-bridge-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
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

```bash
# 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

```bash
# 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

```yaml
# 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.

```bash
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

```bash
# 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

```bash
# 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](https://github.com/muchiny/bridge-mcp/releases/latest) 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

```bash
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:

```yaml
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:

```yaml
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`:

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

### 4. Verify

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

```bash
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.

```mermaid
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.

```yaml
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):**

```yaml
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:**

```yaml
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):

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

**Sudo support:**

```yaml
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:

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

Limits, sanitization & audit

**Limits:**

```yaml
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:

```yaml
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):

```yaml
security:
  require_elicitation_on_destructive: true  # default: false
```

**Audit logging:**

```yaml
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:

```yaml
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` | ssh_exec, ssh_exec_multi (with `diff` / `diff_baseline` / `normalize` for cross-host drift detection), ssh_status, ssh_health, ssh_history, ssh_output_fetch |
| `config` | ssh_config_get, ssh_config_set |
| `file_transfer` | ssh_upload, ssh_download, ssh_sync |
| `file_ops` | ssh_file_read, ssh_file_write, ssh_files_write, ssh_file_chmod, ssh_file_chown, ssh_file_stat, ssh_file_diff, ssh_file_patch, ssh_file_template |
| `sessions` | ssh_session_create, ssh_session_exec, ssh_session_list, ssh_session_close |
| `monitoring` | ssh_metrics, ssh_metrics_multi, ssh_tail, ssh_disk_usage |
| `tunnels` | ssh_tunnel_create, ssh_tunnel_list, ssh_tunnel_close |
| `directory` | ssh_ls, ssh_find |
| `database` | ssh_db_query, ssh_db_dump, ssh_db_restore |
| `redis` | ssh_redis_info, ssh_redis_cli, ssh_redis_keys |
| `postgresql` | ssh_postgresql_query, ssh_postgresql_status |
| `mysql` | ssh_mysql_query, ssh_mysql_status |
| `mongodb` | ssh_mongodb_status |
| `backup` | ssh_backup_create, ssh_backup_list, ssh_backup_restore, ssh_backup_snapshot, ssh_backup_verify, ssh_backup_schedule |
| `docker` | ssh_docker_ps, ssh_docker_logs, ssh_docker_inspect, ssh_docker_exec, ssh_docker_compose, ssh_docker_images, ssh_docker_stats, ssh_docker_volume_ls, ssh_docker_network_ls, ssh_docker_volume_inspect, ssh_docker_network_inspect |
| `podman` | ssh_podman_ps, ssh_podman_logs, ssh_podman_inspect, ssh_podman_exec, ssh_podman_images, ssh_podman_compose |
| `esxi` | ssh_esxi_vm_list, ssh_esxi_vm_info, ssh_esxi_vm_power, 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](https://github.com/muchiny)
- **Source:** [muchiny/bridge-mcp](https://github.com/muchiny/bridge-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-muchiny-bridge-mcp
- Seller: https://agentstack.voostack.com/s/muchiny
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.