ssh-connect MCP server

ssh-connect MCP 服务

** 本项目中的所有代码均由生成式 AI 创建。 **

用于 SSH 连接和文件操作的 MCP 服务。

组件

工具

该服务实现了多个与 SSH 相关的工具：

• connect：连接到 SSH 服务

  • 可选参数，可覆盖环境变量：host、port、username、password、key_path、key_passphrase
  • 返回连接状态

• disconnect：断开与 SSH 服务的连接

  • 无需参数
  • 返回断开连接状态

• execute：在 SSH 服务上执行命令

  • 必需参数：command（字符串）
  • 可选参数：timeout（整数，单位为秒，默认值：60）
  • 返回命令输出（stdout 和 stderr）及退出状态

• upload：将文件上传到 SSH 服务

  • 必需参数：local_path、remote_path
  • 返回上传状态

• download：从 SSH 服务下载文件

  • 必需参数：remote_path、local_path
  • 返回下载状态

• list_files：列出 SSH 服务上某个目录中的文件

  • 必需参数：path
  • 返回文件列表，包含类型和大小信息

配置

可在 MCP 设置中使用环境变量配置 SSH 连接参数：

• SSH_HOST：SSH 服务的主机名或 IP 地址
• SSH_PORT：SSH 服务的端口（默认值：22）
• SSH_USERNAME：SSH 用户名
• SSH_PASSWORD：SSH 密码（使用密码认证时）
• SSH_KEY_PATH：SSH 私钥文件的路径（使用密钥认证时）
• SSH_KEY_PASSPHRASE：SSH 私钥的密码短语（如需要）

必须提供 SSH_PASSWORD 或 SSH_KEY_PATH 以进行身份验证。

配置示例

mcp-config-example.json 中提供了一个 MCP 配置文件示例。你可以将其用作配置 SSH MCP 服务的模板：

{
  "mcpServers": {
    "ssh-connect": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/ssh-connect",
        "run",
        "ssh-connect"
      ],
      "env": {
        "SSH_HOST": "example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "username",
        "SSH_PASSWORD": "password",
        "SSH_KEY_PATH": "/path/to/private_key",
        "SSH_KEY_PASSPHRASE": "key_passphrase"
      }
    }
  }
}

注意：通常只需提供 SSH_PASSWORD 或 SSH_KEY_PATH（以及可选的 SSH_KEY_PASSPHRASE）之一，无需同时提供两者。

示例

examples 目录中提供了一个 Python 脚本，用于演示如何使用 SSH MCP 服务：

• ssh_example.py：演示如何连接到 SSH 服务、执行命令、上传和下载文件、列出目录内容以及断开连接。

运行示例：

python examples/ssh_example.py

此示例假设 SSH MCP 服务已完成配置并正在运行。

与 Cline 配合使用

为了帮助 Cline 了解如何使用 SSH MCP 服务，而无需阅读 README.md 文件，项目提供了以下文件：

• cline_ssh_usage_example.md：使用 Cline 配合 SSH MCP 服务的快速参考指南，包含示例命令和完整工作流。
• create_test_file.py：用于创建测试文件，以测试上传和下载的脚本。
• test_ssh_mcp.sh：一个 shell 脚本，用于创建测试文件，并提供使用 Cline 测试 SSH MCP 服务的分步说明。
• test_ssh_mcp.py：一个 Python 脚本，演示如何直接从 Python 使用 SSH MCP 服务，无需使用 Cline。
• ssh_mcp_guide.html：一份 HTML 指南，包含使用 Cline 配合 SSH MCP 服务的示例和完整工作流。

使用 Cline 测试 SSH MCP 服务：

./test_ssh_mcp.sh

这将创建一个测试文件，并显示使用 Cline 测试 SSH MCP 服务的说明。

直接从 Python 测试 SSH MCP 服务：

./test_ssh_mcp.py

这将对 SSH MCP 服务进行完整测试，包括连接、执行命令、上传和下载文件以及断开连接。

快速入门

安装

一体化设置

如需完整设置并测试 SSH MCP 服务，可以使用一体化设置脚本：

./setup_and_test.sh

此脚本将：

1. 安装所需依赖项
2. 在 Cline 或 Claude Desktop（或两者）中安装 SSH MCP 服务
3. 测试 SSH MCP 服务

手动设置

依赖项

使用 SSH MCP 服务前，需要安装所需的依赖项：

./install_dependencies.sh

此脚本会安装 SSH 连接所需的 Python 包 paramiko。

自动安装

提供了两个 Python 脚本，可自动安装 SSH MCP 服务：

1. 对于 Cline：

./install_ssh_mcp.py

2. 对于 Claude Desktop：

./install_ssh_mcp_claude.py

这些脚本会：

1. 检测配置文件的位置
2. 提示你输入 SSH 连接参数
3. 使用 SSH MCP 服务配置更新配置文件

手动安装

Claude Desktop

claude-desktop-config-example.json 中提供了一个 Claude Desktop 配置文件示例，展示了如何在 Claude Desktop 中配置 SSH MCP 服务。

要在 Claude Desktop 中安装 SSH MCP 服务：

1. 找到 Claude Desktop 配置文件：

   • 在 macOS 上：~/Library/Application\ Support/Claude/claude_desktop_config.json
   • 在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json

2. 将 SSH MCP 服务配置添加到配置文件中的 mcpServers 对象：

{
  "mcpServers": {
    "ssh-connect": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/ssh-connect",
        "run",
        "ssh-connect"
      ],
      "env": {
        "SSH_HOST": "example.com",
        "SSH_PORT": "22",
        "SSH_USERNAME": "username",
        "SSH_PASSWORD": "password",
        "SSH_KEY_PATH": "/path/to/private_key",
        "SSH_KEY_PASSPHRASE": "key_passphrase"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

3. 重启 Claude Desktop 以应用更改。

注意：请务必将占位值替换为实际的 SSH 连接信息。

开发

构建和发布

准备分发软件包：

1. 同步依赖项并更新锁文件：

uv sync

2. 构建软件包分发文件：

uv build

这将在 dist/ 目录中创建源代码分发包和 wheel 分发包。

3. 发布到 PyPI：

uv publish

注意：你需要通过环境变量或命令行标志设置 PyPI 凭据：

• 令牌：--token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

测试

tests 目录中提供了一个测试脚本，用于验证 SSH MCP 服务是否正常工作：

python tests/test_ssh_connect.py

此测试脚本使用 unittest 和模拟，在不实际连接 SSH 服务的情况下测试 SSH MCP 服务的基本功能。

调试

由于 MCP 服务通过 stdio 运行，调试可能颇具挑战。为了获得最佳调试体验，我们强烈建议使用 MCP Inspector。

你可以通过 npm 使用以下命令启动 MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory /path/to/ssh-connect run ssh-connect

启动后，Inspector 会显示一个 URL，你可以在浏览器中访问该 URL 开始调试。