MCP 服务器 SSH 客户端

这是一个模型上下文协议服务器（远程 SSH 客户端），通过 SSH 连接到远程 MCP 服务器。此客户端能够访问和使用托管在远程服务器上的 MCP 工具，提供了一个安全的通道来进行 MCP 通信。

特性

• 通过 SSH 连接到任何 MCP 服务器
• 通过安全的 SSH 通道代理所有 MCP 协议命令
• 支持基于密钥的身份验证
• 支持包括工具、提示和资源在内的 MCP 功能

安装

在一个由 uv 管理的 Python 项目中，可以通过以下方式添加依赖：

uv add m2m-mcp-server-ssh-client

或者，对于使用 pip 来管理依赖的项目：

pip install m2m-mcp-server-ssh-client

直接从源代码安装：

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
pip install -e .

在您的项目中运行服务器：

uv run m2m-mcp-server-ssh-client

常见用例

1. 使用演示服务器快速开始

我们维护了一个公共演示服务器，其中已经配置了多种 MCP 工具并准备就绪。（该服务器将在我们发布开放的去中心化注册表之前一直可用。）

这个演示服务器包含多个 MCP 服务器，包括 HackerNews、MLB 统计 API 和 Formula 1 API 工具供您试验。

Claude

要将 Claude 连接到此服务器，只需在 Claude 桌面设置中添加以下内容：

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

命令行

# Connect to the M2M public demo server with automatic key exchange
uv run m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --use-key-server

2. 本地开发测试

关于设置自己的 SSH 服务器，请参考 m2m-mcp-server-ssh-server。

对于使用自己的 MCP 工具进行本地测试：

# Connect to a local MCP SSH server
uv run m2m-mcp-server-ssh-client

上述命令将尝试连接到监听 8022 端口的本地 SSH 服务器。

在本地测试时，可以通过使用密钥服务器来简化密钥交换：

# Use the key server for automatic key management (if server has --run-key-server enabled)
uv run m2m-mcp-server-ssh-client --use-key-server

上述命令将尝试使用运行在 8000 端口的密钥服务器。

3. 远程服务器连接

连接到您自己托管的 MCP 服务器：

# Using existing SSH keys
uv run m2m-mcp-server-ssh-client --host your-server.example.com --client-key ~/.ssh/your_key --known-hosts ~/.ssh/known_hosts

您可以运行远程服务器上的密钥服务器并在客户端中进行配置，从而简化密钥交换。

与 AI 平台的使用

Claude 桌面集成

在 Claude 桌面设置中添加以下内容：

"mcpServers": {
  "remote-mcp-tools": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "mcp-beta.machinetomachine.ai", 
      "--port", "8022", 
      "--use-key-server"
    ]
  }
}

MCP 检查器

用于调试或探索可用工具：

npx @modelcontextprotocol/inspector -- uvx m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --port 8022 --use-key-server

使用方法

命令行选项

• --host: 远程 SSH 服务器主机（默认："localhost"）
• --port: 远程 SSH 服务器端口（默认：8022）
• --username: SSH 用户名（默认："mcp"）
• --client-key: 客户端私钥文件（默认："~/.ssh/m2m_mcp_server_ssh_client"）
• --known-hosts: 已知主机文件路径（默认："~/.ssh/known_hosts"）
• --passphrase: 私钥的密码短语（默认：无）
• --disable-host-key-checking: 跳过服务器签名验证（默认：False）
• --log-level: 设置日志级别（默认：INFO）

详细示例

基本连接到远程服务器

连接到运行在 8022 端口上的远程 MCP 服务器（SSH 服务器）：

uvx m2m-mcp-server-ssh-client --host mcp.example.com

使用自定义 SSH 密钥

指定特定的 SSH 密钥进行身份验证：

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key

如果您的密钥受密码保护：

uvx m2m-mcp-server-ssh-client --host mcp.example.com --client-key ~/.ssh/mcp_custom_key --passphrase "your-passphrase"

调试模式以解决故障

启用详细的日志记录以解决连接问题：

uvx m2m-mcp-server-ssh-client --host mcp.example.com --log-level DEBUG

密钥服务器集成

MCP SSH 客户端可以使用密钥服务器进行动态密钥交换和验证：

uvx m2m-mcp-server-ssh-client --host mcp.example.com --use-key-server

当使用密钥服务器时：

1. 客户端从 http://host:key-server-port/server_pub_key 获取服务器的公钥
2. 客户端通过 http://host:key-server-port/register 向服务器注册其公钥
3. 为 SSH 连接创建一个临时的 known_hosts 文件

此功能与 --known-hosts 和 --disable-host-key-checking 互斥。

禁用主机密钥检查

⚠️ 安全警告：使用 --disable-host-key-checking 会使您的连接容易受到中间人攻击。仅在受信任的网络中或用于开发/测试目的时使用此选项。

uvx m2m-mcp-server-ssh-client --host localhost --disable-host-key-checking

配置 Claude 桌面

添加到您的 Claude 设置中：

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client", 
      "--host", "example.com", 
      "--port", "8022", 
      "--username", "mcp"
    ]
  }
}

对于更安全的配置，使用特定密钥：

"mcpServers": {
  "remote-servers": {
    "command": "uvx",
    "args": [
      "m2m-mcp-server-ssh-client",
      "--host", "mcp-server.example.com",
      "--port", "8022",
      "--username", "claude-mcp",
      "--client-key", "~/.ssh/claude_mcp_key",
      "--known-hosts", "~/.ssh/mcp_remote_server"
    ]
  }
}

工作原理

MCP 服务器 SSH 客户端与运行 MCP 服务器 SSH 服务器的远程服务器建立 SSH 连接，即 m2m-mcp-server-ssh-server。然后：

1. 创建一个本地代理服务器，该服务器镜像了远程 MCP 服务器的功能
2. 通过 SSH 连接将所有 MCP 请求转发到远程服务器
3. 将远程服务器的响应返回给本地客户端

这使您可以像使用本地安装的工具一样使用远程机器上运行的工具。

认证流程

%%{init: {'theme':'default', 'themeVariables': { 'primaryColor': '#5D8AA8', 'primaryTextColor': '#fff', 'primaryBorderColor': '#1F456E', 'lineColor': '#5D8AA8', 'secondaryColor': '#006400', 'tertiaryColor': '#fff' }}}%%

sequenceDiagram
    participant Host as MCP Host<br>(Claude/Cursor)
    participant Client as MCP SSH Client
    participant KeySrv as Key Server<br>(HTTP API)
    participant SSHSrv as MCP SSH Server
    participant MCP as MCP Servers

    Note over Client,SSHSrv: Initial Key Exchange & Authentication
    
    Client->>Client: Generate SSH key pair<br>if does not exist
    Client->>KeySrv: GET /server_pub_key
    KeySrv->>Client: Return server's public key
    Client->>Client: Store server key in<br>temporary known_hosts
    Client->>KeySrv: POST /register<br>{client_pub_key: "ssh-ed25519 AAAA..."}
    KeySrv->>SSHSrv: Store client public key<br>in authorized keys
    KeySrv->>Client: {status: "success"}
    
    Note over Client,SSHSrv: Secure SSH Connection
    
    Client->>SSHSrv: SSH handshake with<br>client key authentication
    SSHSrv->>SSHSrv: Verify client key<br>against authorized keys
    SSHSrv->>Client: Authentication successful
    
    Note over Client,SSHSrv: MCP Communication
    
    Host->>Client: JSONRPC request
    Client->>SSHSrv: Forward request<br>over SSH tunnel
    SSHSrv->>MCP: Route request to<br>appropriate MCP server
    MCP->>SSHSrv: Process and return results
    SSHSrv->>Client: Send response over SSH
    Client->>Host: Return JSONRPC response
    
    Note over Client,SSHSrv: Session Management
    
    alt Session Termination
        Host->>Client: Close connection
        Client->>SSHSrv: Terminate SSH session
        SSHSrv->>SSHSrv: Clean up resources
    end

安全注意事项

• 在生产环境中始终使用主机密钥验证
• 使用受密码保护的 SSH 密钥以增强安全性
• 考虑为 MCP 连接使用专用的 SSH 密钥
• 为您的 SSH 密钥文件设置适当的权限（600）
• 在远程服务器上使用专门的、权限受限的用户

解决常见问题

连接被拒绝

Error running MCP SSH client: [Errno 111] Connection refused

解决方案：验证主机和端口是否正确，并且 SSH 服务正在运行。

身份验证失败

Error running MCP SSH client: Authentication failed

解决方案: 检查密钥文件路径。确保远程服务器上已安装您的公钥。

主机密钥验证失败

Error running MCP SSH client: Host key verification failed

解决方案: 将主机密钥添加到您的 known_hosts 文件中，或使用 --disable-host-key-checking（仅用于测试）。

依赖项

• anyio (>=4.5.0)
• asyncssh (>=2.20.0)
• mcp (>=1.1.3)
• pydantic (>=2.0.0)

开发

设置开发环境

git clone https://github.com/Machine-To-Machine/m2m-mcp-server-ssh-client.git
cd m2m-mcp-server-ssh-client
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

代码质量

# Run linting
uv run ruff check .

# Run formatting check
uv run ruff format --check .

# Run security checks
uv run bandit -r src/

调试

您可以使用 MCP 检查器来调试客户端：

npx @modelcontextprotocol/inspector uvx m2m-mcp-server-ssh-client --host example.com

对于高级调试，请使用以下工作流程：

1. 使用 --log-level DEBUG 启动客户端
2. 检查 SSH 连接参数和握手过程
3. 如果使用自定义密钥，请验证正确的路径和权限
4. 首先使用 ssh -v 直接测试基本连接

贡献

我们欢迎贡献以帮助扩展和完善 m2m-mcp-server-ssh-client。无论您想添加新功能、增强现有功能还是改进文档，您的输入都是宝贵的。

欢迎提交拉取请求！随时贡献新的想法、错误修复或增强功能。

贡献指南

1. 叉分仓库
2. 创建特性分支：git checkout -b feature-name
3. 提交更改：git commit -am 'Add some feature'
4. 推送到分支：git push origin feature-name
5. 提交拉取请求

许可证

MIT 许可证 - 请参阅 LICENSE 文件以获取详细信息。

作者

• Machine To Machine