SSH-MCP
by keeperlink
README.md
# SSH-MCP
SSH-MCP is a self-hosted [Model Context Protocol](https://modelcontextprotocol.io/)
server for audited SSH commands, bounded file operations and operator-controlled
access. OAuth-protected clients select explicitly allowed SSH hosts; the
service uses pinned host keys and the remote account's existing permissions.
This project is licensed under Apache-2.0. Build the published source
and use the [getting started guide](docs/getting-started.md) to configure
a trusted HTTPS reverse proxy, OAuth and a dedicated SSH account. Public
prebuilt container image availability will be announced separately.
## What it does
- Execute synchronous commands, durable asynchronous jobs and sequential
batches; inspect bounded results after disconnects.
- Request eligible job/batch cancellation, preserving uncertain-outcome status.
- Read/write text, preview/apply multi-file patches and transfer bounded
binary files (native upload currently requires a ChatGPT attachment).
- Require operator decisions for restricted hosts or privileged execution,
with scoped and expiring access grants.
- Display history, approvals and cancellation in the password-protected
**Operator Console** (`/console`).
SSH-MCP is **not a remote shell sandbox**. Authorize only dedicated
least-privilege accounts on hosts you explicitly trust.
## Choose a Docker Compose example
**SSH-MCP needs a trusted HTTPS reverse proxy**, but it does **not**
require Caddy. First configure the application; then choose an HTTPS
setup appropriate to your infrastructure.
| Example | When to use | Public HTTPS |
| --- | --- | --- |
| [Basic](examples/basic/compose.yaml) | You already have HAProxy, Nginx, Traefik or another HTTPS proxy on the same Linux host | Bring your own proxy |
| [Caddy](examples/standalone/compose.yaml) | You do **not** have a proxy and want automatic HTTPS certificates | Bundled optional Caddy |
| [Hardened](examples/hardened/compose.yaml) | You have an existing HTTPS proxy and want tighter container isolation | Bring your own proxy |
Start with [Getting started](docs/getting-started.md). Basic and
hardened Compose bind application HTTP **only to 127.0.0.1** and
**require Docker Engine 28.0.0 or newer** for safe loopback port
isolation. Older Engine releases can expose localhost-published ports
to the same Layer 2 network; do not use these examples on older
versions without an independently reviewed host firewall policy.
They are **not** public HTTPS endpoints on their own. The optional
Caddy example publishes only ports 80/443 and keeps the app on
its private bridge.
For all three: protect private environment files, supply a dedicated
SSH identity, independently verify pinned host keys, enable OAuth,
restrict the remote SSH account and retain audit history. The hardening
example adds defense in depth; it does not replace authentication.
## Documentation
| Topic | Guide |
| --- | --- |
| Start with one application container | [Getting started](docs/getting-started.md) |
| Existing HTTPS proxy or optional Caddy | [HTTPS and reverse proxies](docs/reverse-proxies.md) |
| Additional container restrictions | [Hardening](docs/hardening.md) |
| Settings and inventory | [Configuration](docs/configuration.md) |
| OAuth client login | [OAuth clients](docs/oauth-clients.md) |
| Trust and security boundaries | [Security](docs/security.md) |
| Commands and jobs | [Commands and jobs](docs/commands-jobs.md) |
| Browser history | [Operator Console](docs/operator-console.md) |
| File operations and edits | [File operations](docs/file-operations.md), [Patch workflows](docs/patch-workflows.md) |
| Backups, monitoring, fixes | [Operations](docs/operations.md), [Troubleshooting](docs/troubleshooting.md) |
## Compatibility and development
For upgrades from earlier installations, preserve the persistent database,
signed policy and SSH host-key trust. Read [Upgrade compatibility](docs/upgrade-compatibility.md)
before changing image or state paths.
Development uses Python 3.12; repository validation checks Ruff, strict
mypy, installed-wheel tests, at least 95% combined coverage and a hardened
OCI image. Offline checks do not substitute for separately authorized
real HTTPS/SSH acceptance.
## Contributing and security
See [Contributing](CONTRIBUTING.md) for local validation and pull requests,
and [Security policy](SECURITY.md) for private vulnerability reporting.
## License
SSH-MCP is licensed under the [Apache License 2.0](LICENSE).
See [third-party notices](THIRD_PARTY_NOTICES.md) for dependency licensing.
For maintainers: [Docker Hub publishing](docs/container-publishing.md).