SSH Connector MCP
一个最小化的 SSH 连接器,以 MCP(Model Context Protocol)server 的形式提供,使用 stdio 传输,可被任意 MCP 客户端(Trae、Claude Desktop、Cursor 等)直接配置加载。底层基于 Python + paramiko。
只提供常规 SSH 基础操作:连接/断开、远程执行命令、上传文件、下载文件、列出远程目录。支持密码与私钥两种认证方式,主机指纹始终校验,不提供跳过开关。
目录结构
ssh-connector-mcp/
├── pyproject.toml # 项目与依赖声明、MCP 入口
├── requirements.txt # 依赖列表(pip install -r 用)
├── README.md
└── src/
└── ssh_connector_mcp/
├── __init__.py
├── __main__.py # python -m ssh_connector_mcp
├── server.py # MCP 工具定义 + stdio 启动
└── session.py # 会话管理、SSH/SFTP 操作、主机指纹校验
安装
要求 Python 3.10+。
cd ssh-connector-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
(Linux/macOS 下使用 .venv/bin/python -m pip install -e .。)
安装后会生成 ssh-connector-mcp 命令(位于虚拟环境的 Scripts/ 或 bin/ 下),等价于 python -m ssh_connector_mcp。
MCP 客户端配置示例
把项目虚拟环境中的 Python 绝对路径填入 command(Windows 路径中的反斜杠需要写成 \\):
{
"mcpServers": {
"ssh-connector": {
"command": "C:\\path\\to\\ssh-connector-mcp\\.venv\\Scripts\\python.exe",
"args": ["-m", "ssh_connector_mcp"]
}
}
}
如果虚拟环境的 Scripts/bin 已在 PATH 中,也可以直接使用安装好的入口:
{
"mcpServers": {
"ssh-connector": {
"command": "ssh-connector-mcp"
}
}
}
两种方式都是 stdio 传输,无需额外参数或环境变量。
作为 Trae 插件使用(PyPI + uvx)
plugin/ 目录是按 Trae 插件结构组织的跨平台插件包,运行时由 uvx 从 PyPI 拉取,不包含任何平台相关的二进制:
plugin/
├── .trae-plugin/plugin.json # 插件清单(名称、版本、图标、i18n 描述)
├── .mcp.json # MCP 启动声明:uvx --from ssh-connector-mcp==0.1.0 ssh-connector-mcp
└── assets/icon.svg
前置条件:安装 uv(pip install uv 或官方安装脚本),并确保 uvx 在 PATH 中。
发布到 PyPI:
cd ssh-connector-mcp
uv build # 生成 dist/*.whl 和 dist/*.tar.gz
uv publish # 需要 PyPI API token(UV_PUBLISH_TOKEN 或交互输入)
发布后验证一次:
uvx --from ssh-connector-mcp==0.1.0 ssh-connector-mcp
本地加载插件:把 plugin/ 整体放到插件目录(如 %USERPROFILE%\.trae-cn\plugins\local\ssh-connector\0.1.0\)后重启客户端;具体的本地加载入口以当前客户端版本为准。提交市场时,该目录内容即为插件包。
版本升级时需同步修改三处:pyproject.toml 的 version、plugin/.trae-plugin/plugin.json 的 version、plugin/.mcp.json 中固定的 ssh-connector-mcp==x.y.z。
主机指纹校验
服务端不会自动信任未知主机,也不提供 AutoAddPolicy 之类的跳过选项:
- 连接时加载
~/.ssh/known_hosts;如果传入了known_hosts_path,额外加载该文件。 - 若主机密钥不存在于 known_hosts,或与已记录密钥不一致,连接会被拒绝,错误信息中会给出服务器实际出示的密钥类型与
SHA256:...指纹,以及添加方法,例如:
# 先在可信渠道核对该指纹,再执行(非默认端口请带 -p)
ssh-keyscan -p 22 192.168.1.10 >> ~/.ssh/known_hosts
非 22 端口的 known_hosts 条目形式为 [host]:port,ssh-keyscan -p 会自动按此格式写入。
工具说明
所有工具共用 session_id 来定位连接,默认值均为 "default"。同一时间可用不同 session_id 维持多个连接。
ssh_connect
建立并保留一个 SSH 会话。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
host |
string | 必填 | 远程主机名或 IP |
username |
string | 必填 | 登录用户名 |
password |
string | null |
密码认证;与 private_key_path 至少提供一个 |
private_key_path |
string | null |
私钥文件路径(RSA/ECDSA/Ed25519),支持 ~ |
private_key_passphrase |
string | null |
私钥口令(如私钥有加密) |
known_hosts_path |
string | null |
额外信任的 known_hosts 文件;不存在会报错 |
port |
integer | 22 |
SSH 端口 |
session_id |
string | "default" |
会话名,供后续工具使用;重名会报错 |
connect_timeout |
number | 15 |
TCP/握手/认证超时(秒) |
返回:session_id、host、port、username、server_banner、host_key_type、host_key_fingerprint、known_hosts_files。
不会使用 ssh-agent,也不会自动搜索 ~/.ssh/id_*,认证方式完全由参数决定。
ssh_disconnect
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
session_id |
string | "default" |
要关闭的会话 |
返回 disconnected: true;若会话不存在则返回 disconnected: false,不视为错误。
ssh_execute
执行单条非交互命令,返回输出与退出码。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
command |
string | 必填 | 远程 shell 命令 |
session_id |
string | "default" |
已连接的会话 |
timeout |
number | 60 |
命令最长等待秒数;超时会关闭该 channel |
返回:exit_status、stdout、stderr、truncated(stdout/stderr 各自最多保留 1 MiB,被截断时为 true)。命令以 UTF-8 解码,非法字节替换为 �。
ssh_upload_file
通过 SFTP 上传本地文件,远端同名文件会被覆盖。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
local_path |
string | 必填 | 运行本 MCP server 的机器上的文件路径 |
remote_path |
string | 必填 | 远端目标路径(目录需已存在) |
session_id |
string | "default" |
已连接的会话 |
返回:local_path、remote_path、size。
ssh_download_file
通过 SFTP 下载远端文件,本地父目录会自动创建。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
remote_path |
string | 必填 | 远端源文件路径 |
local_path |
string | 必填 | 本地目标路径 |
session_id |
string | "default" |
已连接的会话 |
返回:remote_path、local_path、size。
ssh_list_directory
列出远端目录内容。
| 参数 | 类型 | 默认值 | 说明 |
|---|---|---|---|
remote_path |
string | "." |
远端目录路径 |
session_id |
string | "default" |
已连接的会话 |
返回 path、count 与 entries,每个条目包含 name、path、type(file / dir / symlink)、size、mode(如 -rw-r--r--)、modified(UTC ISO 8601)。
典型调用顺序
ssh_connect→ 得到一个session_idssh_execute执行uname -a、部署命令等ssh_list_directory/ssh_upload_file/ssh_download_file处理文件ssh_disconnect释放连接(不调用也会在进程退出时自动关闭)
安全说明
- 主机密钥严格校验;未知或变更的密钥直接导致连接失败,并返回 SHA256 指纹便于人工核对。
- 密码、私钥口令只用于当次认证,不会被记录、回显或写入磁盘。
- 连接禁用 ssh-agent 与默认私钥自动搜索,避免隐式使用预期外的凭据。
- 每个会话内的操作串行执行(会话级锁),输出总量有上限,命令有超时。
- 会话仅保存在进程内存中,MCP server 重启后需重新连接。
已知限制
- 只执行单条非交互命令,不提供交互式 shell、PTY 或
sudo密码自动输入。 - 不提供端口转发、跳板机、密钥生成、递归目录传输等扩展能力。
- 所有路径均为运行 MCP server 的本地机器视角;文件内容不经过 MCP 消息传递。
Metadata
Release files for ssh-connector-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| ssh_connector_mcp-0.1.0.tar.gz | 10.4 kB | Without provenance | Details for ssh_connector_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| ssh_connector_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for ssh_connector_mcp-0.1.0-py3-none-any.whl |
Total release size: 21.5 kB
Release files / ssh_connector_mcp-0.1.0.tar.gz
| Download URL | ssh_connector_mcp-0.1.0.tar.gz |
|---|---|
| Size | 10.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
58b2a1183cb9905cab808547caeeeba02b2af972453fac64ed1070b02953252b
|
|
BLAKE2b-256 checksum How to use checksums |
24808b8b5d2d842c942eb4473c046f241fb09bd3a76c310e93dc79c3a3907bd6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Release files / ssh_connector_mcp-0.1.0-py3-none-any.whl
| Download URL | ssh_connector_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 11.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
debe8008b4d0c67ddf62af5da7237f1ff5c7e899760a518fb8ad0368ecc002bd
|
|
BLAKE2b-256 checksum How to use checksums |
97882070ad458fc4c400f90a3bc14d43dd1667c0e78917386ee0e3fa6af9fc91
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.6 {"installer":{"name":"uv","version":"0.13.6","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
|
Security for ssh-connector-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.