purple SSH MCP
The MCP server of the purple SSH manager: an agent reads hosts from ~/.ssh/config and their containers, commands and container control are opt-in
- 761 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Without `--read-only` the agent runs commands on your servers over SSH and stops or restarts containers
- It uses your SSH keys and the configuration in `~/.ssh`, so access is limited only by what those keys open
- In read mode the agent sees addresses, users and container lists of every host in the config
Install
- Works in
Manual install
curl -fsSL getpurple.sh | shOne-script install. Other ways exist too: `brew install erickochen/purple/purple` and `cargo install purple-ssh`.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Without `--read-only` the agent runs commands on your servers over SSH and stops or restarts containers
- It uses your SSH keys and the configuration in `~/.ssh`, so access is limited only by what those keys open
- In read mode the agent sees addresses, users and container lists of every host in the config
This is third-party code. Review the repository files before installing.
What it does
purple is a terminal SSH manager written in Rust for macOS and Linux, and the `purple mcp` command runs it as an MCP server for Claude Code, Cursor and other clients. The agent gets five tools. `list_hosts` and `get_host` return entries from `~/.ssh/config`: alias, address, user, port, key files, ProxyJump and tags. `list_containers` shows Docker or Podman containers on a chosen host over SSH and detects the runtime on its own. `run_command` runs a shell command on the host without interactive input, with a default timeout of 30 seconds and a maximum of 300. `container_action` starts, stops or restarts a container. The `--read-only` flag leaves only the first three tools: the other two are denied and disappear from the list the client gets from the server. Every call, including a denied one, is appended to `~/.purple/mcp-audit.log` as JSON Lines: time, tool, arguments, outcome and reason. The text of a `run_command` command never reaches the log, a marker stands in its place. `--audit-log` changes the log path and `--no-audit` turns it off. The same binary is also the manager itself: search across hundreds of hosts, sync with 18 cloud providers, tunnels, file transfer and signed HashiCorp Vault certificates. For Claude Desktop there is a ready `.mcpb` package in the releases, installed by a double click and read-only.
Who it is for. For administrators and developers whose servers are described in `~/.ssh/config` and who want to give Claude Code or Cursor an overview of hosts and containers without shell access to the servers.
Good fit when
- You want to ask an agent which servers the SSH config describes and which tags they carry
- You need to know which Docker or Podman containers run on a remote host without logging in
- You want to give an agent read-only access to servers with a log of every call
- You already keep your host list in purple and sync it with AWS, Hetzner, Proxmox or another cloud
- Claude Desktop should see your servers after installing a single `.mcpb` file
Not a fit when
- You work on Windows: purple is built for macOS and Linux
- Your hosts are not described in `~/.ssh/config`: the server works only with aliases from it
- You need the agent to transfer files: the MCP part has no such tool, and a separate SFTP server exists, SSH MCP Server (classfang)
- You need interactive access with a password prompt: `run_command` runs without prompts and without interactive programs
Example request
Show all hosts tagged `prod` from my SSH config and list the containers running on `web-1`MCP
- Transport
- stdio
- Authentication
- not required
Limitations
- It runs on macOS and Linux, there are no Windows builds.
- Without the `--read-only` flag the agent gets `run_command` and `container_action`, so it can run commands and change container state on any host in the config. The `.mcpb` package for Claude Desktop does not allow this, and commands need a manual client setup.
- `list_containers` and `container_action` work only if Docker or Podman is installed on the target host.
- The server handles calls one at a time, so a long command delays the next ones.
- purple keeps cloud provider tokens in `~/.purple/providers/*.toml` in plain text, and the `mcp-audit.log` journal is protected with 0600 permissions.
How to disable. Remove the purple entry from your client's MCP settings. For the Claude Desktop package, delete the extension in the app settings. The manager itself is removed the way you installed it, for example `brew uninstall purple`. Delete the `~/.purple` folder with the log and cloud tokens by hand.
FAQ
How do I connect the purple MCP server to Claude Code or Cursor?
Add a server to the MCP settings with the command `purple` and arguments `mcp --read-only`. The client then sees `list_hosts`, `get_host` and `list_containers`. Without `--read-only`, `run_command` and `container_action` are added.
What can an agent do in read-only mode?
Read the host list and the details of an alias from the SSH config and look at containers on a remote host. The server denies a `run_command` or `container_action` call and logs the denial with the a read-only mode note.
How do I check what the agent did on my servers?
Open `~/.purple/mcp-audit.log`: each line is one call with time, tool, arguments, outcome and denial reason. For `run_command` a marker replaces the arguments so command-line passwords do not settle on disk.
Can I install purple for Claude Desktop with one file?
Yes. Download the `.mcpb` package from the latest release and open it with a double click. The extension is read-only and gives the same three tools: `list_hosts`, `get_host` and `list_containers`.
How long can a command run through run_command?
30 seconds by default. The agent can pass a timeout parameter from 1 to 300 seconds, and the server clips a larger value to 300. Interactive programs do not fit: the command runs in BatchMode.
Where does purple get the list of servers?
From `~/.ssh/config`, which it edits while keeping comments and formatting. The `purple sync` command pulls hosts from cloud providers, including AWS, GCP, Azure, Hetzner, Proxmox and OCI.
Discussion
No questions or reviews yet.
Related
MCP serversMCP SSH Manager
mcp-ssh-manager
Managing several SSH connections from Claude Code and Codex: commands, file transfer, databases and backups
SSH MCP
ssh-mcp
A security-first SSH server: command classification, policy authorization and several sign-in methods. It runs commands on remote servers
SSH MCP Server (classfang): remote commands over SSH
SSH MCP Server (classfang)
An SSH MCP server: the agent runs commands, reads and writes files over SFTP, transfers files and starts long jobs while credentials stay with you
Self-hosted MCP server for running commands on remote servers over SSH, with tokens and roles
A proxy between MCP transports: connects stdio clients to remote SSE and HTTP servers and exposes local servers over the network
Containarium: isolated boxes for AI agents
Containarium
A platform on your own server that gives each agent its own Linux box with SSH and MCP tools for commands and files
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| purple SSH (this entry) | yes | not required | 761 | |
| MCP SSH Manager | no | API key | 527 | manages several SSH connections from Claude Code and Codex: commands, file transfer, databases and backups |
| SSH MCP Server (classfang): remote commands over SSH | no | not required | 988 | runs commands and reads and writes files over SFTP, with passwords staying with the user |
README in short
The repository holds the Rust sources with tests, fuzzing of the SSH config parser and Nix and AUR builds, along with PRIVACY.md listing network calls and SECURITY.md. The `.mcpb` package manifest lists three tools for Claude Desktop. The `llms.txt` file describes the manager's features for models, and a changelog is kept per version. MIT license.