ssh MCP server
2026년 11월 14일 커밋설정된 호스트에 대해 MCP 클라이언트를 위한 제어된 SSH 명령 실행 및 SFTP 파일 작업을 제공합니다.
다른 이름 ralscha/ssh-mcp
- 스타
- 0
- Tools
- 17
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 14일
- 라이선스
- MIT
ssh MCP란?
설정된 호스트에 대해 MCP 클라이언트를 위한 제어된 SSH 명령 실행 및 SFTP 파일 작업을 제공합니다. 17개 도구를 제공합니다. 예: list-connections, read-command, run-command.
프로젝트 README에서 생성된 요약
ssh MCP server 정보
ssh-mcp는 MCP 클라이언트를 사용하는 개발자가 제어된 SSH 및 SFTP 작업을 통해 원격 서버를 관리할 수 있게 해줍니다. 이 MCP server는 설정된 호스트로 연결되는 보안 중심의 브릿지 역할을 하며, 전체 대화형 터미널을 제공하지 않고도 명령 실행과 파일 조작을 가능하게 합니다. private key, SSH-agent, Windows Pageant를 포함한 다양한 인증 방법을 지원하며, 기존 OpenSSH 설정을 가져와 복잡한 jump host 또는 bastion 설정을 처리할 수 있습니다.
사용자는 안전한 검사를 위한 read-command, 광범위한 작업을 위한 run-command, 그리고 파일 관리를 위한 SFTP 도구 모음과 같은 특정 도구를 통해 서버와 상호작용합니다. 이 서버는 정책 기반 명령, shell-quoted 템플릿, 위험한 작업에 대한 사용자 승인 방식을 사용하여 안전성을 최우선으로 합니다. 또한 원자적 파일 쓰기(atomic file writes), 체크섬 검증, 변조 방지 감사 로그 기능을 갖추어 모든 작업이 기록되고 검증될 수 있도록 보장합니다. stdio 또는 인증된 streamable HTTP 전송 방식을 통해 실행할 수 있습니다.
활용 사례
- 1원자적 설정 업데이트AI에게 현재 파일의 무결성을 확인한 후 원격 파일에 특정 코드 패치를 적용하도록 지시합니다.
- 2관리형 백그라운드 프로세스AI에게 원격 호스트에서 장시간 실행되는 작업을 시작하고 진행 상황을 모니터링하도록 요청합니다.
- 3보안 파일 전송AI가 원자적 쓰기 작업을 사용하여 새로운 설정 파일을 원격 디렉토리에 업로드하도록 합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
ssh MCP 도구 17
README에서 감지됨list-connectionsread-commandrun-commandlist-command-templatesrun-command-templatediagnose-connectionstart-commandsftp-uploadsftp-downloadsftp-readsftp-checksumsftp-write
| list-connections | — | |
| read-command | — | |
| run-command | — | |
| list-command-templates | — | |
| run-command-template | — | |
| diagnose-connection | — | |
| start-command | — | |
| sftp-upload | — | |
| sftp-download | — | |
| sftp-read | — | |
| sftp-checksum | — | |
| sftp-write | — |
도구 17개 모두 보기도구 수 줄이기
sftp-apply-patchsftp-mkdirsftp-renamesftp-removerisky
| sftp-apply-patch | — | |
| sftp-mkdir | — | |
| sftp-rename | — | |
| sftp-remove | — | |
| risky | — |
구성
SSH_MCP_DEV_KEY_PASSPHRASE
| 이름 | 설명 | 유형 |
|---|---|---|
| SSH_MCP_DEV_KEY_PASSPHRASE | — |
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능ralscha/ssh-mcp is public and reachablegithub.com/ralscha/ssh-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-14github.com/ralscha/ssh-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음17 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨No tool named like delete, drop or exec통과
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기ssh-mcp
A small, security-conscious Model Context Protocol server that gives MCP clients controlled SSH access to configured hosts. It uses the official Go MCP SDK, x/crypto/ssh, and SFTP.
The server supports:
- reusable SSH connections with password, private-key, SSH-agent, or native Windows Pageant authentication;
- optional selection of one Pageant/agent key by SHA-256 fingerprint;
- OpenSSH config imports and chained
ProxyJump/bastion connections; - strict
known_hostsverification or an exact SHA-256 host-key pin; - policy-gated read-only, general, and shell-quoted template commands;
- human approval for risky operations through MCP elicitation/multi-round-trip input;
- command timeouts, cancellation, bounded output, optional PTY, and stdin;
- server-enforced SFTP timeouts and bounded HTTP request bodies;
- persistent background jobs, progress notifications, and the stable MCP Tasks extension;
- structured, bounded SFTP listing, stat, range reads, checksums, atomic writes, and guarded unified patches;
- structured directory creation, rename, and non-recursive removal;
- tamper-evident, redacted JSONL auditing;
- stdio plus authenticated Streamable HTTP transport, including OAuth introspection mode.
The server deliberately does not provide an interactive terminal. Commands remain bounded requests or cancellable background jobs so policy, auditing, and output limits continue to apply. Root logins and profiles without a command allowlist fail closed unless their explicit opt-ins are set.
Installation
Download a release archive for your platform from the repository's Releases page, verify it against checksums.txt, and place ssh-mcp (or ssh-mcp.exe) on your PATH.
Build
Go 1.27 or newer is expected by this module:
go build -o ssh-mcp.exe ./cmd/ssh-mcp
go test ./...
On Linux or macOS, use -o ssh-mcp instead.
Run ssh-mcp --version to verify the installed build. Version 1.0.0 release archives contain the executable, this README, the license, and the example configuration.
Configure
Copy config.example.toml to the platform config path:
| Platform | Default path |
|---|---|
| Linux | ~/.config/ssh-mcp/config.toml |
| macOS | ~/Library/Application Support/ssh-mcp/config.toml |
| Windows | %AppData%\ssh-mcp\config.toml |
You can also pass --config PATH. On Unix, the config must not be readable or writable by group/others; use chmod 600.
Passwords and private-key passphrases are read only from environment variables. For a profile named prod-web, resolution is:
SSH_MCP_PROD_WEB_PASSWORD, thenSSH_MCP_PASSWORD;SSH_MCP_PROD_WEB_KEY_PASSPHRASE, thenSSH_MCP_KEY_PASSPHRASE.
For agent authentication, set auth = "agent". On Linux and macOS the server uses SSH_AUTH_SOCK. On Windows it automatically uses native PuTTY Pageant when Pageant is running, with no bridge or SSH_AUTH_SOCK required; otherwise it tries the Windows OpenSSH agent at \\.\pipe\openssh-ssh-agent. Pageant must already be running with at least one suitable key loaded.
If an agent contains many keys, set agentKeyFingerprint = "SHA256:..." on the profile. Only that key is offered, avoiding MaxAuthTries failures. diagnose-connection lists the loaded public-key fingerprints and reports which one is selected; it never returns private material.
OpenSSH config and jump hosts
Set sshConfigHost on a profile to fill missing HostName, User, Port, IdentityFile, and ProxyJump values from ~/.ssh/config:
[[profiles]]
name = "production"
sshConfigHost = "prod-web"
Alternatively, defaults.importSSHHosts = ["prod-web", "staging"] creates profiles for exact aliases. A referenced ProxyJump alias is imported automatically as a jump-only profile: it can carry the SSH connection but cannot be targeted by MCP tools. Explicit TOML values override imported OpenSSH values. Include directives and wildcard/negated Host patterns are supported; conditional Match blocks are intentionally ignored. For multiple hops, chain configured profiles with proxyJump rather than using a comma-separated OpenSSH value.
Host-key verification is strict by default. The server uses knownHostsFile, normally ~/.ssh/known_hosts, unless trustedHostKey pins an exact SHA256:... fingerprint. hostKeyMode = "insecure" and per-profile insecureSkipHostKey = true exist for isolated test hosts and emit a warning; do not use them for real systems.
MCP client setup
Build the executable, then add it to your MCP client's configuration:
{
"mcpServers": {
"ssh": {
"command": "C:\\path\\to\\ssh-mcp.exe",
"args": ["--config", "C:\\path\\to\\config.toml"],
"env": {
"SSH_MCP_DEV_KEY_PASSPHRASE": "optional-passphrase"
}
}
}
}
If the default config file does not exist, the MCP handshake and tools/list still work, but every tool call returns a clear unconfigured error.
Tools
| Tool | Purpose |
|---|---|
list-connections |
List profiles and lazy connection state. |
read-command |
Run one conservative, allowlisted read-only command without shell operators. |
run-command |
Run a command after built-in and configured policy checks. |
list-command-templates |
List narrowly scoped operations configured for a profile. |
run-command-template |
Render a template with shell-quoted arguments, then apply normal policy. |
diagnose-connection |
Test DNS, direct/proxied TCP, agent keys, host key, and authentication separately. |
start-command |
Start a persistent, cancellable background command. |
job-status, job-output, cancel-job |
Poll and manage a background job by its unguessable ID on clients without Tasks support. |
sftp-upload |
Atomically upload UTF-8 or base64 content. Mutating; denied on read-only profiles. |
sftp-download |
Download a bounded file as UTF-8 or base64. |
sftp-list, sftp-stat |
Inspect directories and path metadata. |
sftp-read |
Read a bounded file byte range. |
sftp-checksum |
Calculate a bounded remote file's SHA-256. |
sftp-write |
Alias for atomic sftp-upload. |
sftp-apply-patch |
Apply a unified diff after checking the current SHA-256, then atomically replace the file. |
sftp-mkdir |
Create a directory, optionally including missing parents. |
sftp-rename |
Rename a path, with explicit opt-in for destination replacement. |
sftp-remove |
Remove one file, symlink, or empty directory; recursive deletion is not supported. |
audit-list, audit-verify |
Read redacted events and verify the hash chain. |
read-command recognizes common inspection commands such as ls, cat, grep, ps, stat, systemctl status/show, docker ps/logs/inspect, and kubectl get/logs/describe. It rejects shell operators and redirection. Git is intentionally excluded because repository configuration can invoke helper programs and some nominally observational Git commands can update the index; expose a deliberately constrained Git command template if needed.
run-command is broader, but always blocks a narrow catastrophic set such as filesystem formatting, dd ... of=/dev/..., root-recursive removal, shutdown/reboot, pipe-to-shell installers, fork bombs, and destructive root permission changes. These rules reduce accidents; they are not a shell sandbox. A profile must configure at least one allowedCommands expression before run-command or start-command can be used. Setting allowUnrestrictedCommands = true bypasses only that allowlist requirement and should be reserved for isolated, trusted environments; built-in and configured deny rules still apply.
When allowedCommands is non-empty, a command must match at least one expression. Global and per-profile denyCommands are applied first. Invalid regular expressions stop startup.
Command templates use {{parameter}} placeholders. Every supplied value is POSIX-shell quoted, undeclared or missing arguments are rejected, and the rendered command still passes through the same deny/allow and catastrophic-command checks. Set readOnly = true only for a genuinely non-mutating template; requiresApproval = true forces confirmation.
Approvals
approvalMode can be set globally or per profile:
risky(default) requests confirmation for privilege escalation, service/package/firewall changes, deletion, permission changes, selected Git/container/Kubernetes mutations, shell redirection, file replacement, and patching;alwaysrequests confirmation for every mutating action;neverrelies on server policy without interactive confirmation.
Current MCP sessions receive an InputRequests approval and automatically retry after the user answers. Older sessions use elicitation through the SDK compatibility flow. Declined, missing, expired, modified, or unsupported approvals fail closed. Catastrophic commands remain blocked and cannot be approved.
Background jobs and MCP Tasks
start-command returns a normal job object to ordinary clients. Clients that declare io.modelcontextprotocol/tasks in their per-request extension capabilities receive a stable 2026-07-28 CreateTaskResult instead and can call tasks/get, tasks/cancel, and tasks/update. The server only returns the polymorphic Task result after explicit client opt-in.
Job metadata and bounded output are persisted to jobStateFile; command strings are intentionally not persisted. Running jobs are marked failed after a server restart because SSH cannot reattach to an already detached process. Completed handles remain pollable until jobRetentionMs expires. Clients must retain the job ID returned by start-command; there is intentionally no global job-list tool because a list can disclose other callers' task handles. Non-Tasks callers with a progress token receive start and terminal progress notifications.
SFTP mode is a JSON integer: Unix 0600 is decimal 384, and 0644 is decimal 420. Omit it for 0600.
sftp-apply-patch requires expectedSha256, normally obtained from sftp-checksum. The checksum is rechecked immediately before upload. SFTP has no portable compare-and-swap primitive, so another writer can still race the final rename; use remote OS permissions or a command template with application-specific locking when strict cross-process serialization is required. Patch targets must be regular UTF-8 files; symlinks, directories, and special files are rejected.
Writes use a sibling temporary file, request an SFTP fsync when supported, and use the OpenSSH POSIX rename extension for atomic replacement. If the destination exists and that extension is unavailable, the write fails instead of silently degrading to a non-atomic replacement.
Audit log
Set defaults.auditLog to enable append-only JSONL auditing. Events include the profile, action, redacted command or target, authorization decision, outcome, duration, exit code, and transferred byte count. Each event hashes its content and the previous event hash; startup and audit-verify reject a modified chain. The log is forced to owner-only permissions where the platform supports them.
Built-in redaction covers common password/token/secret assignments, bearer tokens, and PEM private keys. Add installation-specific regular expressions with defaults.auditRedact. Avoid putting secrets directly in commands in the first place; use the server's environment-based credential resolution.
Streamable HTTP and OAuth
Stdio is the default. Set [http].enabled = true to serve stateless Streamable HTTP at listen plus path, including MCP revision 2026-07-28. authMode = "token" compares the bearer credential against tokenEnv in constant time. Non-loopback listeners require a TLS certificate and key, and browser origins must be same-origin or explicitly listed in allowedOrigins. Requests larger than maxRequestBytes are rejected with HTTP 413.
For a shared deployment, authMode = "oauth":
- publishes OAuth protected-resource metadata at the RFC 9728 path derived from
resourceUrl(for example/.well-known/oauth-protected-resource/mcp) with the pathless endpoint retained for compatibility; - challenges unauthenticated requests with
WWW-Authenticateandresource_metadata; - validates access tokens through RFC 7662 introspection;
- verifies expiry, audience/resource, and every configured required scope;
- caches only a SHA-256 token identifier and the short-lived validation result, never the token itself.
The OAuth introspection client ID and secret come from oauthClientIdEnv and oauthClientSecretEnv. The authorization server, resource URL, and introspection endpoint must use HTTPS.
Security notes
- Avoid root SSH accounts.
- If root access is unavoidable, it must be acknowledged with
allowRoot = true; use a dedicated profile with a very narrow allowlist and approval modealways. - Prefer a dedicated remote user with OS-level permissions matching the task.
- Keep strict host-key verification enabled.
- Use a narrow
allowedCommandslist for production profiles. - Prefer command templates over arbitrary
run-commandaccess. - Mark inspection-only profiles with
readOnly = true; this disablesrun-commandand uploads. - Keep
approvalMode = "risky"oralwaysunless the MCP client cannot present approvals. - Keep HTTP on loopback unless TLS and OAuth are configured.
- OAuth scopes authorize the server as a whole; for tenant- or user-specific profile isolation, run separate instances with separate configuration, audit, and job-state files.
- Run only one server process per
auditLogandjobStateFile; these files use atomic replacement and process-local synchronization, not cross-process locking. - MCP tool annotations are hints to clients, not access controls. Enforcement happens in the server before opening an SSH channel.
Development
gofmt -w cmd internal
go vet ./...
go test ./...
go build ./cmd/ssh-mcp
The repository also includes the same Taskfile, GoReleaser, lint configuration, and test/release workflow layout used by jira-mcp. Run task check for the local release gate.
License
MIT - see LICENSE.
ssh MCP 질문
ssh MCP는 어떤 도구를 제공하나요?
17개 도구를 제공합니다. 예: list-connections, read-command, run-command, list-command-templates, run-command-template.
서버 인증은 어떻게 하나요?
비밀번호, private-key, SSH-agent 또는 Windows Pageant 인증을 지원합니다.
기존 OpenSSH 설정을 사용할 수 있나요?
네, 프로필에 sshConfigHost를 설정하면 ~/.ssh/config에서 HostName, User, Port, IdentityFile, ProxyJump 값을 가져올 수 있습니다.
명령 실행은 안전한가요?
서버는 정책 기반 명령, 명령 타임아웃을 사용하며, 위험한 작업에 대해서는 MCP elicitation을 통해 사용자의 승인을 요구할 수 있습니다.
백그라운드 작업을 지원하나요?
네, MCP Tasks 확장을 통해 진행 상황 알림과 함께 지속적인 백그라운드 작업을 지원합니다.