【免费下载链接】ssh-mcp-server基于 SSH 的 MCP 服务 ‍♀️。已被MCP官方收录 。 SSH MCP Server ‍♀️. It has been included in the community MCP repository .项目地址https://gitcode.com/gh_mirrors/ss/ssh-mcp-server点击查看免费下载ssh-mcp-server 是一个基于 SSH 的 MCPModel Context Protocol服务器它用 TypeScript 把 MCP 协议和 ssh2 库桥接起来让 AI 助手能安全地远程执行 SSH 命令、传输文件。本文将带你从入口文件读起逐层拆解它的架构全景。️ 项目结构先看清五大模块整个项目源码在 src/ 目录下按职责清晰地分成五层这是理解架构的关键模块路径职责入口层src/index.ts解析--help/--version启动服务核心层src/core/mcp-server.ts组装 MCP 服务器、注册工具、生命周期管理工具层src/tools/注册 AI 可调用的工具命令执行、文件传输等服务层src/services/ssh-connection-manager.ts项目的心脏管理与远程服务器的 SSH 连接工具函数层src/utils/日志、SSH config 解析、路径校验、错误定义此外src/models/types.ts 定义了贯穿全项目的核心类型src/config/server.ts 则提供 MCP 服务器名与版本号。这种入口 → 核心 → 工具 → 服务的分层正是典型的薄 MCP 层 厚 SSH 服务层设计MCP 协议相关的代码很少绝大部分复杂度都被收敛到 SSH 连接管理器里。⚡ 启动流程从 CLI 参数到 MCP 服务器第一步命令行参数解析程序入口 src/index.ts 非常精简——它只处理--help和--version然后创建SshMcpServer并调用run()index.ts → new SshMcpServer() → run()真正的参数解析在 src/cli/command-line-parser.ts 中完成。它把几十种命令行参数--host、--port、--privateKey、--whitelist、--transport-mode……归一化成SshConnectionConfigMap——也就是连接名 → 连接配置的映射支持多 SSH 连接同时管理。所有连接字段host、port、认证方式、黑白名单、超时等的完整定义在 SSHConfig 接口 中这份接口是理解全部配置项的字典。第二步组装并连接 MCP 服务器核心类 SshMcpServer 的构造函数只有两件事用 MCP 官方 SDK 的McpServer创建服务器实例获取SSHConnectionManager的单例。run()方法src/core/mcp-server.ts的完整启动顺序是解析 CLI 参数 → 注入连接配置 → 注册退出信号 → 注册全部工具 → 创建 StdioServerTransport → server.connect(transport) → 安全警告检查 → 可选预连接所有服务器这里有两个值得注意的桥接细节stdio 传输它使用StdioServerTransport意味着 AI 客户端如 Claude Code、Cursor通过标准输入输出与服务通信无需打开端口这也是 MCP 服务器最常见的部署方式凭据隔离SSH 密码、私钥全部由本地进程持有只存在于 src/services/ssh-connection-manager.ts 的内存中永远不会出现在 MCP 消息里暴露给 AI 模型——这是整个项目最重要的安全设计。️ 工具层AI 能调用的 8 个能力所有工具的注册集中在 src/tools/index.ts 的registerAllTools中一眼就能看清项目对外的全部能力面工具源码说明execute-commandsrc/tools/execute-command.ts执行远程命令并取回输出upload/downloadsrc/tools/upload.ts / src/tools/download.tsSFTP 文件传输支持目录read-file/write-filesrc/tools/file-io.tsSFTP 读写文本文件支持分页list-serverssrc/tools/list-servers.ts列出所有配置的 SSH 服务器job-start/job-status/job-kill/job-listsrc/tools/jobs.ts长任务后台执行与轮询以 execute-command.ts 为例每个工具文件的写法高度一致用zod定义输入参数cmdString、connectionName、timeout……并自动转换为 MCP 的 inputSchema调用SSHConnectionManager单例执行实际逻辑结果统一包装成{ content: [{ type: text, text }] }返回。所以工具层其实只是一层协议适配器——它把AI 发起的 JSON 请求翻译成服务层的方法调用这正是 TypeScript 桥接 MCP 与 ssh2 的第一座桥。一个有趣的设计grep无匹配这类非零退出码会被当作正常结果返回输出末尾附[exit code] N而不是工具错误避免 AI 误判命令失败execute-command.ts。 核心桥接SSHConnectionManager 与 ssh2SSHConnectionManager 是全文最值得细读的文件约 3000 行。它用单例模式管理多路 SSH 连接内部维护一组按连接名索引的 Map客户端clients、连接状态connected、白名单正则、shell 会话流等。双传输模式exec 与 shellrunCommandInternalsrc/services/ssh-connection-manager.ts是命令执行的统一入口流程为命令黑白名单校验 → 确保连接就绪 → 按 transportMode 分流 ├─ exec 模式client.exec() 打开独立通道默认 └─ shell 模式复用持久 shell 会话串行执行堡垒机场景exec 模式走 runExecCommand直接调用 ssh2 的client.exec()用StringDecoder处理跨 chunk 的多字节字符并对输出做maxOutputBytes截断保护防止cat大文件撑爆内存shell 模式针对只暴露交互式 shell 的堡垒机连接成功后先打开一个持久 shell 通道通过带唯一标记marker的探测命令等待shell 就绪之后所有命令排队串行执行——标记解析还用了增量扫描优化避免每个数据块都全量重扫缓冲区ShellScanState 注释。文件传输SFTP 的两种策略upload/download走 SFTP且实现了自适应策略upload 方法文件大于 256 KiB 时用fastPut/fastGet以 64 并发、32 KiB 分片流水线传输高延迟链路上速度远优于单请求流式传输小文件或/proc/cpuinfo这类伪文件无法获取真实大小回退到流式pipeline避免并发策略反而变慢下载先写临时文件、成功后再原子改名失败自动清理保证不会出现半截文件。️ 安全防线与错误系统三层命令/路径防护命令黑白名单setConfig时把正则字符串预编译为RegExpssh-connection-manager.ts启用白名单时含;、|、反引号等 shell 元字符的命令直接拒绝本地路径校验validateLocalPath通过realpath解析符号链接后检查是否落在允许的根目录内防路径遍历源码远端路径校验allowedRemotePaths限制 SFTP 可读写范围防止 AI 被提示注入后触碰~/.ssh/authorized_keys等敏感文件。面向 AI 的结构化错误src/utils/tool-error.ts 定义了ToolError携带code如COMMAND_TIMEOUT、SFTP_ERROR、message和retriable三个字段。这套稳定的错误契约让上层 Agent 能程序化地决定重试还是报错是面向 AI 消费方设计的一个细节。 架构全景一张图收尾把前面的线索串起来ssh-mcp-server 的数据流全景是AI 客户端Claude Code / Cursor 等 │ stdioJSON-RPC / MCP 协议 ▼ SshMcpServersrc/core/mcp-server.ts │ registerAllTools ▼ Tools 层src/tools/── zod 校验参数 ──┐ ▼ SSHConnectionManager单例src/services/ │ 白名单校验 / 路径沙箱 / 超时控制 ▼ ssh2 Clientexec 通道 / 持久 shell / SFTP │ SSH 协议 ▼ 远程 Linux / Windows 服务器一句话总结MCP SDK 负责说 AI 听得懂的话ssh2 负责真正干远程的活而 TypeScript 的强类型SSHConfig、ToolError像胶水一样把两者粘成一条类型安全、边界清晰的管道。这种薄协议层 强类型服务层的分层也正是你在设计自己的 MCP 服务器时可以直接抄作业的架构范式。 延伸阅读完整功能与配置说明README.md / README_EN.md交互式配置技能skills/ssh-mcp-helper/SKILL.md单元测试覆盖test/ 目录连接管理、命令执行、路径解析等赞分享【免费下载链接】ssh-mcp-server基于 SSH 的 MCP 服务 ‍♀️。已被MCP官方收录 。 SSH MCP Server ‍♀️. It has been included in the community MCP repository .项目地址https://gitcode.com/gh_mirrors/ss/ssh-mcp-server点击查看免费下载相关推荐Chrome MCP Server 架构深度解析从 MCP 协议桥接到 SIMD 加速的 AI 浏览器自动化引擎Chrome MCP Server 架构深度解析从 MCP 协议桥接到 SIMD 加速的 AI 浏览器自动化引擎 本文基于开源仓库 mcp chrome ht人工智能AI 应用MCP 服务浏览器控制如何快速掌握Apple MCP项目从MCP协议到AppleScript的完整技术指南如何快速掌握Apple MCP项目从MCP协议到AppleScript的完整技术指南 Apple MCPGitHub 加速计划是一个专注于模型上下文协议如何让AI操作BlenderBlenderWorld的MCP桥接与Blender MCP服务器架构深入解读如何让AI操作BlenderBlenderWorld的MCP桥接与Blender MCP服务器架构深入解读 BlenderWorld 是首个专门评估前沿 AI上一篇kimi-free-api 报错排查速查从 errcode 到日志的完整排障手册下一篇如何在工作中高效学习英语ToastFish帮你利用碎片时间提升词汇量创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考