MCP Server SSH Client

MCP Server SSH Client

一个模型上下文协议服务（远程 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 Stats API 和 Formula 1 API 工具，供你体验。

Claude

要将 Claude 连接到此服务，只需将以下内容添加到 Claude Desktop 设置中。

"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 Desktop

将以下内容添加到 Claude Desktop 设置中：

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

MCP Inspector

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

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：私钥的密码短语（默认值：None）
• --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 Client 可以使用密钥服务器进行动态密钥交换和验证：

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 Desktop 配置

将以下内容添加到 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 Server SSH Client 会与运行 MCP Server SSH Server 的远程服务器建立 SSH 连接，以使用 MCP 工具，即 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 inspector 调试客户端：

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. Fork 此仓库
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