MCP Server SSH Client

MCP Server SSH Client

Machine-To-Machine

开发者工具
访问服务器

README

MCP 服务器 SSH 客户端

PyPI version Python Versions License: MIT

一个模型上下文协议服务器（远程 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"
    ]
  }
}

命令行

# 连接到 M2M 公共演示服务器，并自动进行密钥交换
uv run m2m-mcp-server-ssh-client --host mcp-beta.machinetomachine.ai --use-key-server

2. 本地开发测试

有关设置您自己的 SSH 服务器，请参阅 m2m-mcp-server-ssh-server。

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

# 连接到本地 MCP SSH 服务器
uv run m2m-mcp-server-ssh-client

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

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

# 使用密钥服务器进行自动密钥管理（如果服务器启用了 --run-key-server）
uv run m2m-mcp-server-ssh-client --use-key-server

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

3. 远程服务器连接

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

# 使用现有的 SSH 密钥
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 客户端可以使用密钥服务器进行动态密钥交换和验证：

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 服务器 SSH 客户端建立与运行 MCP 工具的远程服务器（即 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]"

代码质量

# 运行 linting
uv run ruff check .

# 运行格式检查
uv run ruff format --check .

# 运行安全检查
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。无论您是想添加新功能、增强现有功能还是改进文档，您的投入都很有价值。

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

贡献指南

  1. Fork 存储库
  2. 创建一个功能分支：git checkout -b feature-name
  3. 提交您的更改：git commit -am 'Add some feature'
  4. 推送到分支：git push origin feature-name
  5. 提交 Pull Request

许可证

MIT 许可证 - 有关详细信息，请参阅 LICENSE 文件。

作者

  • Machine To Machine

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript