safe-ssh-mcp

Safe SSH MCP 服务

一个安全且范围受限的 SSH MCP 服务，用于通过 SSH 执行只读诊断命令。
在本项目中，“安全”特指主机安全：此服务旨在防止修改远程系统，并降低造成运行事故的风险。它并不试图保证外部 Agent 无法滥用命令输出。

徽章

- 安全检查

概述

此 MCP 服务的核心理念是安全至上。它不会为 AI Agent 提供不受限制的 bash shell，而是仅开放经过精心筛选的只读命令，用于系统诊断和监控。

可用工具（部分列表）

1. get_disk_free ：df -h
2. get_disk_usage ：find <path> -mindepth 1 -maxdepth 1 -exec du -sh -- {} + 2>/dev/null | sort -rh | head -n 20
3. get_dmesg ：dmesg
4. get_uptime ：uptime
5. get_current_datetime ：date
6. get_distroname_version ：cat /etc/os-release
7. get_systemd_list_all ：systemctl list-units --all --no-pager
8. get_systemd_list_failed ：systemctl list-units --state=failed --no-pager
9. get_systemd_list_timers ：systemctl list-timers --no-pager
10. get_crontab_tasks：crontab -l
11. get_systemd_status ：systemctl status {daemon}
12. get_top ：top -b -n 1 -c

点击打开可用工具完整列表

调用示例

okay, could u check disk usage on /root/ path with help of safe-ssh-mcp server on a remote myserver.mydomain.pro using root and /Users/myUser/.ssh/id_rsa to login?

连接方式

此服务支持 SSH 账号密码认证和私钥认证。在 mcp_config.ini 中配置私钥口令来源：

# ENV_VAR (SSH_KEY_PASSPHRASE) or KEYCHAIN (ssh-agent)
ssh_key_passphrase_method=ENV_VAR

1. SSH 账号密码：向 MCP 工具提供 password。不要将其用于私钥口令。

2. 未加密的 SSH 密钥：使用 key_path。默认的 ENV_VAR 设置也支持未加密的密钥；无需设置 SSH_KEY_PASSPHRASE。

3. 使用环境变量提供受口令保护的 SSH 密钥：保留 ssh_key_passphrase_method=ENV_VAR，在启动 MCP 服务的环境中设置 SSH_KEY_PASSPHRASE，并提供 key_path。

   export SSH_KEY_PASSPHRASE='your-key-passphrase'
   safe-ssh-mcp
   

4. macOS 钥匙串 / SSH Agent：设置 ssh_key_passphrase_method=KEYCHAIN，然后在启动 MCP 服务的同一用户会话中解锁密钥。服务会从 ssh-agent 接收 SSH 签名；它不会读取密钥口令或 key_path。

   ssh-add --apple-use-keychain ~/.ssh/id_ed25519
   
   # Optional: make the loaded identity expire after one hour.
   ssh-add -t 1h ~/.ssh/id_ed25519
   
   # Remove one identity, or clear every loaded identity.
   ssh-add -d ~/.ssh/id_ed25519
   ssh-add -D
   

5. 从 macOS Dock 启动 Cursor：使用 KEYCHAIN（推荐）。你可以在任意终端窗口运行 ssh-add；它会更新 macOS 登录会话的 SSH Agent，因此无需从该终端启动 Cursor。

   ssh-add --apple-use-keychain ~/.ssh/id_ed25519
   ssh-add -l
   

   更改 mcp_config.ini 后，在 Cursor 中重启 MCP 服务（或完全退出并重新打开 Cursor）。在 KEYCHAIN 模式下调用工具时，请省略 key_path；Agent 会从已加载的身份中进行选择。

   如果必须使用 ENV_VAR，请在从 Dock 打开 Cursor 前，在 macOS launchd 会话中设置该变量，然后完全退出并重新打开 Cursor：

   launchctl setenv SSH_KEY_PASSPHRASE 'your-key-passphrase'
   

   此值仅在当前登录会话中有效，而且直接在命令中输入口令可能会将其保存到 shell 历史记录中。建议使用 KEYCHAIN。

对于 KEYCHAIN，MCP 服务必须继承该用户会话中的 SSH_AUTH_SOCK。从桌面应用启动的 stdio 服务通常会自动继承。ENV_VAR 会将口令存储在服务进程环境中，因此请限制对该进程的访问，并避免将其提交到源代码管理中。

更新日志

项目内容

1. mcp_ssh.py - SSH MCP 服务
2. mcp_config.ini - 服务配置
3. check_health_sse.py - 检查服务的工具以及服务是否正常运行（SSE 传输）
4. check_health_stdio.py - 检查服务的工具以及服务是否正常运行（stdio 传输）

兼容性

在 MacOS 上使用 Python3.11 连接远程 Ubuntu 服务进行手动测试
使用 Python 3.11、3.12、3.13、3.14 进行自动化测试

MCP Registry

mcp-name: io.github.Areso/safe-ssh-mcp

许可证

本项目采用 GNU AGPLv3 许可证。

为什么采用 AGPL？

此服务充当核心基础设施，不包含业务逻辑。采用 AGPL 许可证，可以确保添加到服务中的任何安全改进、错误修复或新诊断工具都能回馈给开源社区。

面向客户端开发者的说明

由于 MCP 客户端通过标准的进程间通信（IPC）或网络协议（如 HTTP/SSE）与此服务通信，AGPL 许可证不会“传染”或限制连接到此服务的客户端应用程序。
你可以安全地将专有、闭源或宽松许可（如 MIT、Apache 2.0）的 AI Agent 连接到此服务，而不会违反许可条款。