AIエージェントが制御されたSSHコマンドの実行やSFTPファイル転送を行うための、監査ログとコマンドポリシーを備えた集中型HTTPゲートウェイを提供します。
別名 gelse/ssh-mcp
- スター
- 8
- ツール
- 6
- ダウンロード数(30日間)
- —
- 最新バージョン
- 0.3.0
- 最終コミット
- 2026年9月16日
- ライセンス
- MIT
ssh MCPとは
AIエージェントが制御されたSSHコマンドの実行やSFTPファイル転送を行うための、監査ログとコマンドポリシーを備えた集中型HTTPゲートウェイを提供します。 6個のツールを提供しており、ssh_list_servers, ssh_list_allowed_commands, ssh_execute_commandなどがあります。
プロジェクトのREADMEから生成された概要
ssh MCP server について
複数のAIエージェントによるリモートサーバーへのアクセス管理を、制御されたSSHおよびSFTP機能を提供する集中型HTTPゲートウェイによって、より安全にします。クライアントごとに個別のローカルプロセスを実行する代わりに、このサーバーは単一のエントリポイントとして機能し、厳格なコマンドポリシーと監査ログを適用しながらSSHターゲットに接続します。SSHキーの乱立を防ぎ、エージェントがインフラ上で実行しているコマンドの可視性を維持する必要がある運用チーム向けに設計されています。
ユーザーはDocker経由でサーバーをデプロイし、APIキーで認証してstreamable HTTPを使用してMCPクライアントを接続します。システムは、ssh_list_servers、ssh_list_allowed_commands、ssh_execute_command、ssh_check_connection、ssh_download_file、ssh_upload_fileの6つの特定のツールを提供します。9層の認可チェーン、セッションを再利用するためのコネクションプーリング、および暴走したエージェントによるホストへの過負荷を防ぐレート制限を備えている点が特徴です。設定はJSONファイルで管理され、ターゲットやコマンドの許可リストに対してホットリロードをサポートしています。
できること
- 1リモートエージェントのアクティビティを監査開発者は、構造化されたJSONLログを通じて、AIエージェントが行ったすべてのコマンドと認可の決定を追跡できます。
- 2エージェントの権限を制限管理者は、ターゲットごとに許可される特定のコマンドを定義し、エージェントが安全な操作のみを実行できるようにできます。
- 3SFTPによる単一ファイルの転送AIクライアントは、安全なファイル転送ツールを使用して、リモートサーバーとの間で個別のファイルを移動できます。
- 4サーバーの過負荷を防止ゲートウェイはレート制限を使用し、単一のエージェントが1分あたりの設定されたリクエスト数を超えないようにします。
プロジェクトの README から作成されています。すべてのユースケースは、その引用と照らし合わせて確認されています。
ssh MCPのインストール方法
フォーマット検証日 2026年11月10日Cursor に追加Gooseに追加Claude Codeにssh MCPをインストール
$ claude mcp add --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' ssh-mcp -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Cursorにssh MCPをインストール
~/.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>"
}
}
}
}VS Codeにssh MCPをインストール
.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>"
}
}
}
}VS Code CLIにssh MCPをインストール
$ 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>"}}'Claude Desktopにssh MCPをインストール
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>"
}
}
}
}Codexにssh MCPをインストール
$ codex mcp add ssh-mcp --env 'CONFIG_API_TOKEN=<YOUR_CONFIG_API_TOKEN>' -- docker run -i --rm ghcr.io/gelse/ssh-mcp:0.3.0Codex config.tomlにssh MCPをインストール
~/.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>"
Gemini CLIにssh MCPをインストール
$ 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.0Gemini settings.jsonにssh MCPをインストール
~/.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>"
}
}
}
}ssh MCPツール 6
READMEから検出ssh_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 | — |
設定
CONFIG_API_TOKENシークレットBearer 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
| 名前 | 説明 | 種類 |
|---|---|---|
| CONFIG_API_TOKEN | Bearer token for the configuration API | シークレット |
| 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 |
自動チェック
実行日 2026年11月12日完全なレポート →自動チェックに合格しました。これはセキュリティ監査ではありません。コードを読み、サーバーに必要最小限のアクセス権を与えてください。 チェックの仕組み
- ソースリポジトリがリンクされており、アクセス可能合格
- オープンソースライセンス (OSI)合格
- 過去1年以内にコミットまたはリリースあり合格
- パッケージ名が有名なパッケージに酷似していない未チェック
- リモートエンドポイントがHTTPSを使用未チェック
- 破壊的なツールがラベル付けされている合格
- モデルへの隠れた指示がない合格
- パッケージおよびその依存関係に重大な勧告なし未チェック
README
GitHubで見るssh-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
ssh MCPのよくある質問
ssh MCPを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.0を実行します。すべてのプロジェクトで利用するには--scope userを追加します。
ssh MCPをCursorに追加するには
~/.cursor/mcp.jsonを開き、上記のインストールセクションに示すCursor設定を使ってmcpServersの下にサーバーを追加します。
ssh MCPが提供するツールは
6個のツールを提供しており、ssh_list_servers, ssh_list_allowed_commands, ssh_execute_command, ssh_check_connection, ssh_download_fileなどがあります。
MCPクライアントはどのように接続しますか?
クライアントは、指定されたホストとポートでstreamable HTTPトランスポートを使用してサーバーに接続し、ヘッダーにAPIキーを渡します。
対話型シェルはサポートしていますか?
いいえ、このサーバーは対話型シェルではありません。コマンドは構造化された出力とともに個別に実行されます。
ホットリロードはどのように機能しますか?
設定ファイルは15秒ごとにポーリングされ、2秒のデバウンスが適用されます。これにより、再起動することなく変更を反映できます。