ssh-connect MCP服务器

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

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

组件

工具

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

• connect: 连接到SSH服务器

  • 可选参数以覆盖环境变量：host（主机），port（端口），username（用户名），password（密码），key_path（密钥路径），key_passphrase（密钥短语）
  • 返回连接状态

• disconnect: 从SSH服务器断开连接

  • 不需要任何参数
  • 返回断开连接状态

• execute: 在SSH服务器上执行命令

  • 必需参数：command（字符串）
  • 可选参数：timeout（整数，秒，默认值：60）
  • 返回命令输出（标准输出和标准错误）及退出状态

• 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配置文件mcp-config-example.json。您可以将其作为模板来配置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），而不是两者都提供。

示例

提供了示例Python脚本位于examples目录下，演示如何使用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使用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配置文件claude-desktop-config-example.json。这展示了如何在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和mock来测试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开始调试。