Menyediakan HTTP gateway terpusat bagi AI agent untuk menjalankan perintah SSH dan transfer file SFTP yang terkontrol dengan audit logging serta kebijakan perintah.
Juga dikenal sebagai gelse/ssh-mcp
- Stars
- 8
- Tools
- 6
- Unduhan, 30 hari
- —
- Versi terbaru
- 0.3.0
- Commit terakhir
- 16 Sep 2026
- Lisensi
- MIT
Apa itu ssh MCP?
Menyediakan HTTP gateway terpusat bagi AI agent untuk menjalankan perintah SSH dan transfer file SFTP yang terkontrol dengan audit logging serta kebijakan perintah. Server ini menyediakan 6 tool, seperti ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command.
Ringkasan dibuat dari README proyek
Tentang ssh MCP server
Mengelola akses server jarak jauh untuk berbagai AI agent menjadi lebih aman melalui HTTP gateway terpusat yang menyediakan kapabilitas SSH dan SFTP yang terkontrol. Alih-alih menjalankan proses lokal individual untuk setiap client, server ini bertindak sebagai satu titik masuk tunggal yang terhubung ke target SSH Anda sambil menerapkan kebijakan perintah yang ketat dan audit logging. Server ini dirancang untuk tim operasional yang ingin mencegah penyebaran SSH key yang tidak terkendali dan menjaga visibilitas terhadap perintah apa saja yang dijalankan agent pada infrastruktur mereka.
Pengguna dapat men-deploy server melalui Docker dan menghubungkan MCP client mereka menggunakan Streamable HTTP dengan autentikasi API key. Sistem ini menyediakan enam tool spesifik: ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command, ssh_check_connection, ssh_download_file, dan ssh_upload_file. Keunggulannya terletak pada rantai otorisasi sembilan lapis, connection pooling untuk menggunakan kembali sesi, dan rate limiting untuk mencegah agent yang tidak terkendali membebani host. Konfigurasi dikelola melalui file JSON yang mendukung hot-reloading untuk target dan allowlist perintah.
Apa yang bisa Anda lakukan dengannya
- 1Audit aktivitas agent jarak jauhDeveloper dapat melacak setiap perintah dan keputusan otorisasi yang dibuat oleh AI agent melalui log JSONL terstruktur.
- 2Batasi izin agentAdministrator dapat menentukan perintah tertentu yang diizinkan untuk target yang berbeda guna memastikan agent hanya menjalankan operasi yang aman.
- 3Transfer file tunggal via SFTPAI client dapat memindahkan file individual ke atau dari server jarak jauh menggunakan tool transfer file yang aman.
- 4Cegah overload serverGateway ini menggunakan rate limiting untuk memastikan satu agent tidak melampaui jumlah request per menit yang telah ditetapkan.
Ditulis berdasarkan README proyek. Setiap use case diperiksa terhadap kutipan dari README tersebut.
Cara menginstal ssh MCP
Format diverifikasi 10 Nov 2026Tambahkan ke CursorTambahkan ke GooseInstal ssh MCP di Claude Code
$ claude mcp add --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Instal ssh MCP di Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"ssh-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Instal ssh MCP di VS Code
.vscode/mcp.json
{
"servers": {
"ssh-mcp": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Instal ssh MCP di VS Code CLI
$ code --add-mcp '{"name":"ssh-mcp","type":"stdio","command":"docker","args":["run","-i","--rm","ghcr.io/gelse/ssh-mcp:0.3.0"],"env":{"CONFIG_API_TOKEN":"<YOUR_CONFIG_API_TOKEN>"}}'Instal ssh MCP di Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"ssh-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Instal ssh MCP di Codex
$ codex mcp add ssh-mcp --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Instal ssh MCP di Codex config.toml
~/.codex/config.toml
[mcp_servers.ssh-mcp] command = "docker" args = ["run", "-i", "--rm", "ghcr.io/gelse/ssh-mcp:0.3.0"] [mcp_servers.ssh-mcp.env] CONFIG_API_TOKEN = "<YOUR_CONFIG_API_TOKEN>"
Instal ssh MCP di Gemini CLI
$ gemini mcp add -s user -e 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp docker -- run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Instal ssh MCP di Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"ssh-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/gelse/ssh-mcp:0.3.0"
],
"env": {
"CONFIG_API_TOKEN": "<YOUR_CONFIG_API_TOKEN>"
}
}
}
}Tool ssh MCP 6
Terdeteksi dari READMEssh_list_serversssh_list_allowed_commandsssh_execute_commandssh_check_connectionssh_download_filessh_upload_file
| ssh_list_servers | — | |
| ssh_list_allowed_commands | — | |
| ssh_execute_command | — | |
| ssh_check_connection | — | |
| ssh_download_file | — | |
| ssh_upload_file | — |
Konfigurasi
CONFIG_API_TOKENRahasiaBearer token for the configuration API
CONFIG_API_ENABLEDEnable the configuration REST API and web dashboard
CONFIG_DIRDirectory containing ssh-mcp-config.json
LOG_DIRDirectory for JSONL audit logs
| Nama | Deskripsi | Tipe |
|---|---|---|
| CONFIG_API_TOKEN | Bearer token for the configuration API | Rahasia |
| CONFIG_API_ENABLED | Enable the configuration REST API and web dashboard | |
| CONFIG_DIR | Directory containing ssh-mcp-config.json | |
| LOG_DIR | Directory for JSONL audit logs |
Pengecekan otomatis
Berjalan 12 Nov 2026Laporan lengkap →Lolos checks otomatis kami. Ini bukan audit keamanan: baca kodenya dan berikan server akses paling terbatas yang dibutuhkannya. Cara kerja checks
- Source repository terhubung dan dapat dijangkauLolos
- Lisensi open source (OSI)Lolos
- Ada commit atau release dalam satu tahun terakhirLolos
- Nama package tidak mirip dengan package populerTidak diperiksa
- Remote endpoint menggunakan HTTPSTidak diperiksa
- Tools yang bersifat destruktif telah diberi labelLolos
- Tidak ada instruksi tersembunyi untuk modelLolos
- Tidak ada advisory kritis pada paket atau dependensinyaTidak diperiksa
README
Lihat di GitHubssh-mcp
A centralized MCP gateway that gives AI agents controlled SSH access over Streamable HTTP.
What problem does this solve?
Most MCP SSH servers run as local stdio processes — one per client, with no shared state, no centralized authorization, and no audit trail. When multiple AI agents need SSH access, each manages its own SSH keys and runs its own process. This creates:
- No centralized access control — every client decides what it can run
- No audit trail — commands are invisible to the ops team
- SSH key sprawl — keys scattered across every agent machine
- No rate limiting — a runaway agent can overwhelm a target
ssh-mcp solves this by deploying a single HTTP gateway. All clients connect to it; it connects to your SSH targets. Authorization, rate limiting, connection pooling, and audit logging happen in one place.
Quick Start
Using the pre-built image (recommended)
docker compose pull
docker compose up -d
The image is published at ghcr.io/gelse/ssh-mcp:latest.
The compose file maps host port 9080 to container port 8080.
Verify the server is running:
curl http://localhost:9080/health
# → {"status": "ok"}
Create a minimal config in config/ssh-mcp-config.json:
{
"version": 1,
"ssh_targets": {
"my-server": {
"host": "10.0.1.10",
"username": "deploy"
}
},
"allowed_commands": {
"default": [
{
"targets": ["*"],
"commands": ["hostname", "uptime", "free", "df"]
}
]
}
}
Generate an API key hash and add it to your config or
secrets.json (see Configuration).
make build
docker compose up -d --build
What you can do (tools)
Six MCP tools are available over Streamable HTTP:
| Tool | Description |
|---|---|
ssh_list_servers |
List configured SSH targets |
ssh_list_allowed_commands |
Show allowed commands for a target |
ssh_execute_command |
Execute a command on a remote server |
ssh_check_connection |
Test SSH connectivity to a target |
ssh_download_file |
Download a file via SFTP |
ssh_upload_file |
Upload a file via SFTP |
Tool Naming Convention
All tools follow the pattern ssh_<verb>_<noun>:
ssh_list_servers— list resourcesssh_list_allowed_commands— list permissionsssh_execute_command— perform an actionssh_check_connection— verify connectivityssh_download_file/ssh_upload_file— file transfer
See examples/README.md for usage examples
including curl commands and Python client code.
What's configurable
ssh-mcp is configured via JSON files with hot-reload (15 s poll, 2 s debounce). Key areas:
| Area | Details |
|---|---|
| SSH targets | Host, port, username, key, password |
| Command policies | Block patterns, per-key/network allowlists |
| Connection pool | Max connections, idle timeout, concurrency |
| Rate limiting | Per-IP sliding window (default 60 req/min) |
| Logging | JSONL with rotation, gzip, multiple targets |
| SFTP | Sandbox root, path length limits |
Full reference: docs/CONFIGURATION.md
| File | Purpose |
|---|---|
ssh-mcp-config.json |
Main config |
config.schema.json |
JSON Schema for validation |
secrets.json |
Passwords and API key hashes |
MCP_SSH_* env vars |
Overrides for any setting |
Why not just raw SSH / other MCP servers?
ssh-mcp adds a layered authorization chain (9 ordered layers) between every client request and every SSH command. Per-API-key and per-network rules let different agents get different permissions on different servers — without touching the underlying SSH accounts.
Additional protections:
- Circuit breakers isolate failing targets with exponential backoff
- Rate limiting prevents runaway agents from overwhelming hosts
- Structured audit logs trace every command, client, IP, and authorization decision
- Connection pooling reuses SSH sessions across requests
- Input sanitization and dangerous-pattern detection block shell injection attempts
Architecture: ARCHITECTURE.md
Security model: docs/SECURITY.md
What it is NOT
- Not an interactive shell — commands are executed individually with structured output
- Not a file manager — SFTP supports single-file download and upload only (no directory listing or recursive transfer)
- Not a firewall / network ACL — authorization is command-level, not network-level
- Does not reduce SSH account privileges — if a command is allowed, the SSH user executes it with whatever privileges that account has
Not yet / known gaps
Fixable with contribution:
- SFTP is single-file only — no directory listing or recursive transfer
- No TLS termination — run Traefik or nginx in front
- No OAuth or mTLS app-layer authentication
- Rate limiter settings are not hot-reloadable (set at boot)
Architectural:
- Config API dashboard login sessions are in-memory only — they don't survive restarts and the API is single-instance (config changes themselves persist to the config file normally)
- No tamper protection for audit logs
Observability
- Health:
GET /health— returns{"status": "ok"} - Metrics:
GET /metrics— Prometheus exposition format - Logging: Structured JSONL with request correlation
Full reference: docs/OBSERVABILITY.md
Config API & Dashboard
An optional web dashboard for managing configuration without
editing JSON files. Enable with CONFIG_API_ENABLED=true.
Full reference: docs/CONFIG-API.md
FAQ
Dashboard returns 401 over HTTP
The session cookie defaults to Secure (HTTPS only). For local
HTTP testing, set:
environment:
- CONFIG_API_SESSION_COOKIE_SECURE=false
Then restart the container.
How do MCP clients connect?
Connect to http://host:9080/mcp using the Streamable HTTP
transport. Pass your API key via X-API-Key or
Authorization: Bearer header.
How do I generate an API key hash?
docker compose exec mcp-ssh python -c \
"from lib.crypto import hash_api_key; print(hash_api_key('your-key'))"
# → pbkdf2:sha256:100000$<salt>$<hash>
Or use the hash utility in the Config API dashboard.
How does hot reload work?
The config file is polled every 15 seconds with a 2-second debounce. Changes to targets, commands, and settings take effect without restart. Rate limiter and log target settings require a restart.
Why was my command denied?
Commands are evaluated through a 9-layer authorization chain.
The matched_via field in logs shows which layer denied.
See Security Model for the full chain.
How does rate limiting work?
Per-IP sliding window, default 60 requests per 60 seconds.
Exceeding the limit returns HTTP 503. Configure via
settings.rate_limit in the config file.
Where do logs go?
Logs are written to the /logs volume (mapped from ./logs).
The active log file is ssh-mcp.log in JSONL format with
optional gzip rotation.
Troubleshooting basics
# Check server health
curl http://localhost:9080/health
# Validate config
make config-test
# Check logs
docker compose logs mcp-ssh
Documentation
| Document | Description |
|---|---|
ARCHITECTURE.md |
System design and data flow |
docs/SECURITY.md |
Security model and threat analysis |
docs/CONFIGURATION.md |
Full config reference |
docs/CONFIG-API.md |
Config API & dashboard |
docs/OBSERVABILITY.md |
Health, metrics, logging |
CONTRIBUTING.md |
Development and contribution guide |
CHANGELOG.md |
Release history |
examples/ |
Config examples and client code |
Development
# Unit tests
make test
# Integration tests (builds Docker image)
make integrationtest
See CONTRIBUTING.md for the full development
guide, coding conventions, and PR workflow.
Roadmap
No public roadmap. See Not yet / known gaps for current limitations and opportunities.
License
Pertanyaan tentang ssh MCP
Bagaimana cara menambahkan ssh MCP ke Claude Code?
Jalankan claude mcp add --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0 di terminal Anda. Tambahkan --scope user agar tersedia di semua proyek.
Bagaimana cara menambahkan ssh MCP ke Cursor?
Buka ~/.cursor/mcp.json dan tambahkan server di bawah mcpServers, menggunakan config Cursor yang ditunjukkan di bagian instalasi di atas.
Tool apa yang disediakan ssh MCP?
Server ini menyediakan 6 tool, termasuk ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command, ssh_check_connection, ssh_download_file.
Bagaimana cara client MCP terhubung?
Client terhubung ke server menggunakan transport Streamable HTTP pada host dan port yang ditentukan, dengan menyertakan API key di dalam header.
Apakah mendukung interactive shell?
Tidak, server ini bukan interactive shell; perintah dijalankan satu per satu dengan output terstruktur.
Bagaimana cara kerja hot reload?
File konfigurasi akan diperiksa setiap 15 detik dengan debounce 2 detik, sehingga perubahan dapat langsung diterapkan tanpa perlu restart.