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 理解如何在不读取 README.md 文件的情况下使用 SSH MCP 服务器，提供了以下文件：

• 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

此脚本将安装 paramiko Python 包，这是 SSH 连接所必需的。

自动安装

提供了两个 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: --token 或 UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME 和 --password/UV_PUBLISH_PASSWORD

测试

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

python tests/test_ssh_connect.py

此测试脚本使用 unittest 和 mocking 来测试 SSH MCP 服务器的基本功能，而无需实际连接到 SSH 服务器。

调试

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

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

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

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