Token导航 LogoToken导航TokenDH.com
中转站排行榜
MCP Remote Exec logo
AI代理stdio官方级别未说明来源级核验

MCP Remote Exec

MCP Server

一个提供SSH访问远程服务器的MCP服务器，允许AI助手通过自然语言界面执行命令、传输文件和管理系统。

工具数

11

提示词数

0

GitHub Stars

2

资源数

0
PythonClaude系统管理Claude DesktopClaude

安装说明

本站只整理中文说明和来源信息，不托管安装包，也不代用户安装。

GitHub

作者 / 组织

husniadil

提供方

husniadil

最后核验

2026/5/17 20:20

运行时

Python

快速接入

先看主来源和安装命令，再打开仓库或文档；下面只保留这个条目的关键接入事实。

命令预览

uv run mcp-remote-exec --version

详细介绍

SSH MCP远程执行器

一种模型上下文协议（MCP）服务器，提供对远程服务器的SSH访问，允许AI助手通过自然语言接口执行命令、传输文件和管理系统。

⚠️ 免责声明

英语：

使用风险自负。 该软件在您的远程基础设施上提供直接SSH访问和命令执行功能。此软件的开发人员是 不负责任 对于使用此软件可能引起的任何损坏、数据丢失、系统故障、安全漏洞或任何其他问题。

通过使用此软件，您承认：

  • 您了解让AI系统SSH访问您的基础设施的风险
  • 您全权负责在执行之前审查和批准命令
  • 您有适当的备份和灾难恢复程序
  • 您不会要求开发商对任何损害或损失承担责任

本软件按“原样”提供，不提供任何形式的明示或暗示担保。

建筑

此MCP服务器遵循干净/六边形架构原则，并明确分离了关注点：

核心层（单向依赖）

应用程序具有严格的分层，每一层仅依赖于其下的层：

  • 第0层：公用 -跨所有层使用的共享实用程序、枚举和验证器
  • 第1层：配置 -SSH主机设置、安全设置、配置管理
  • 第二层：数据访问 -SSH连接、SFTP操作、域异常
  • 第三层：服务 -业务逻辑、验证、输出格式、数据访问包装器
  • 第4层：演示 -FastMCP工具、输入模型、AI接口

成分根

  • Bootstrap模块 (presentation/bootstrap.py)-中央初始化点，知道所有层和线的依赖关系
  • 包根 (__init__.py)-为方便起见，通过从所有层重新导出来提供公共API

注意：虽然引导模块和包根都从所有层导入，但代码库的其余部分保持严格的单向依赖关系。

扩展

  • 插件系统 -扩展核心功能的可选功能（例如，Proxmox容器管理、ImageKit文件传输）。插件从公共层访问共享代码，并通过服务层访问功能。

依赖关系规则

  • 演示→ 服务→ 数据访问→ 配置（单向，无向上依赖）
  • 公共层可以由任何层（共享实用程序）导入
  • 服务层为数据访问操作提供包装器，以保持层分离
  • Bootstrap模块处理所有跨层初始化
  • 插件通过ServiceContainer的依赖注入进行集成
  • 插件从公共层导入共享实用程序（枚举、验证器）；业务逻辑依赖关系通过ServiceContainer来自服务层

特性

核心功能

  • ✅ 执行bash命令 在远程SSH服务器上
  • ✅ 文件传输操作 （上传/下载）使用SFTP
  • ✅ 连接管理 具有自动清理功能
  • ✅ 安全特性 -风险接受、验证、超时
  • ✅ 标准模式 -原生Claude桌面集成
  • ✅ CLI工具 -可安装为 uv run mcp-remote-exec

插件系统

  • ✅ 可扩展架构 -添加特定于域的功能
  • ✅ 有条件激活 -通过环境变量启用插件
  • ✅ Proxmox插件 -Proxmox VE的容器管理（LXC容器）
  • ✅ ImageKit插件 -HTTP网关场景的两阶段文件传输

插件

ImageKit插件

当MCP服务器在HTTP网关后面运行时，ImageKit插件启用文件传输，因为直接SFTP连接不起作用。它使用ImageKit作为两阶段传输的临时存储桥。

激活：设置ImageKit凭据和 ENABLE_IMAGEKIT=true 在你的 .env 文件

需求：ImageKit帐户（免费版可在https://imagekit.io)

何时使用:

  • MCP服务器通过HTTP网关运行（非直接连接）
  • 客户端和服务器之间无法直接进行SFTP
  • 需要使用短期令牌进行安全的文件传输

可用工具 （4个工具）：

  • imagekit_request_upload -启动上传（步骤1/3）
  • imagekit_confirm_upload -完成上传（步骤3/3）
  • imagekit_request_download -启动下载（步骤1/3）
  • imagekit_confirm_download -完成下载（步骤3/3）

运作原理:

上传：客户端→ ImageKit→ 服务器\ 下载：服务器→ ImageKit→ 客户端

配置示例:

# .env
I_ACCEPT_RISKS=true
HOST=192.168.1.100
SSH_USERNAME=root
SSH_PASSWORD=secret

# ImageKit credentials
IMAGEKIT_PUBLIC_KEY=your_public_key
IMAGEKIT_PRIVATE_KEY=your_private_key
IMAGEKIT_URL_ENDPOINT=https://ik.imagekit.io/your_id
IMAGEKIT_FOLDER=/mcp-remote-exec  # Optional: organize files in a folder
IMAGEKIT_TRANSFER_TIMEOUT=3600  # Optional: transfer timeout in seconds (default: 3600 = 1 hour)
ENABLE_IMAGEKIT=true

示例用法:

# Upload file to server
imagekit_request_upload(remote_path="/data/file.txt", permissions=644)
# Returns curl command - execute it to upload file
# Then confirm:
imagekit_confirm_upload(transfer_id="abc-123-def")

# Download file from server
imagekit_request_download(remote_path="/data/file.txt")
# Returns download URL - execute curl to download
# Then confirm cleanup:
imagekit_confirm_download(transfer_id="abc-123-def")

工具更换:

启用ImageKit插件时(ENABLE_IMAGEKIT=true 具有有效凭据）：

  • ❌ ssh_upload_file -未注册（使用 imagekit_request_upload + imagekit_confirm_upload)
  • ❌ ssh_download_file -未注册（使用 imagekit_request_download + imagekit_confirm_download)
  • ❌ proxmox_upload_file_to_container -未注册（ImageKit提供统一的文件传输）
  • ❌ proxmox_download_file_from_container -未注册（ImageKit提供统一的文件传输）
  • ✅ ssh_exec_command -仍然可用
  • ✅ 所有Proxmox容器管理工具(proxmox_container_exec_command等）-仍然可用

备注：ImageKit工具通过以下方式支持Proxmox容器 ctid 参数，为所有文件传输提供统一的接口。

有关详细文档，请参阅 插件/imagekit/README.md

Proxmox插件

Proxmox插件为Proxmox VE提供容器管理工具。它使AI助手能够通过专门的命令管理LXC容器。

激活：设置 ENABLE_PROXMOX=true 在你的 .env 文件

需求：您的SSH主机必须是Proxmox VE服务器

可用工具:

容器管理（始终可用-5个工具）：

  • proxmox_container_exec_command -在容器内执行命令
  • proxmox_list_containers -列出所有LXC容器
  • proxmox_container_status -获取容器状态（运行/停止）
  • proxmox_start_container -启动已停止的容器
  • proxmox_stop_container -停止正在运行的容器

文件传输（有条件-2个工具，如果启用ImageKit则禁用）：

  • proxmox_download_file_from_container -从容器下载文件
  • proxmox_upload_file_to_container -将文件上传到容器

工具分离:

  • 核心工具 处理Proxmox主机操作（使用 ssh_exec_command, ssh_upload_file等等）
  • 插件工具 处理容器特定操作（使用 proxmox_* 工具）

备注：如果启用了ImageKit插件，Proxmox文件传输工具将被支持 ctid 集装箱操作参数

配置示例:

# .env
I_ACCEPT_RISKS=true
HOST=192.168.1.100    # Your Proxmox host
SSH_USERNAME=root
SSH_PASSWORD=secret
ENABLE_PROXMOX=true   # Activate plugin

示例用法:

# Host operations (use core tools)
ssh_exec_command("pvecm status")                   # Check cluster status
ssh_exec_command("df -h")                          # Check host disk space
ssh_download_file("/etc/pve/storage.cfg", "./storage.cfg")

# Container operations (use plugin tools)
proxmox_list_containers()                          # List all containers
proxmox_container_exec_command(ctid=100, command="apt update")  # Update container
proxmox_upload_file_to_container(ctid=100, local_path="./app.conf", container_path="/etc/app/app.conf")

有关详细文档，请参阅 插件/proxmox/README.md

安装

先决条件

  • Python 3.12.x（尚未支持3.13+）
  • SSH访问远程服务器
  • 与MCP兼容的AI助手（例如Claude Desktop）

快速安装

# Clone the repository
git clone https://github.com/husniadil/mcp-remote-exec.git
cd mcp-remote-exec

# Install dependencies and setup package
uv sync

# Verify installation
uv run mcp-remote-exec --version

从源代码安装

# Install in development mode
pip install -e .
# Or
python -m pip install -e .

配置

复制示例配置并对其进行修改：

cp .env.example .env
nano .env  # Edit your configuration

所需配置

# REQUIRED: Accept risks
I_ACCEPT_RISKS=true

# SSH host configuration
HOST=192.168.1.100
SSH_USERNAME=root
SSH_PASSWORD=your_password

# OR use SSH key authentication
SSH_KEY=/path/to/your/private_key

可选设置

# Maximum character limit for command output (default: 25000)
CHARACTER_LIMIT=25000

# Maximum file size for transfers in bytes (default: 10MB)
MAX_FILE_SIZE=10485760

# Default timeout for commands (default: 30 seconds)
TIMEOUT=30

# Optional: SSH port (default: 22)
SSH_PORT=22

# SSH host key verification (default: true)
# true = Reject connections to unknown hosts (secure, requires known_hosts)
# false = Auto-accept unknown hosts (convenient for containers/dev, less secure)
SSH_STRICT_HOST_KEY_CHECKING=true

命令输入限制：

  • 最大命令长度：10000个字符
  • 最大命令超时：300秒（5分钟）

用法

CLI命令

# Help and version
uv run mcp-remote-exec --help    # Long form
uv run mcp-remote-exec -h        # Short form
uv run mcp-remote-exec --version # Long form
uv run mcp-remote-exec -v        # Short form

# Run server
uv run mcp-remote-exec              # Start stdio mode (Claude Desktop)

Claude桌面设置

  1. 打开克劳德桌面配置：

- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - 视窗: %APPDATA%\Claude\claude_desktop_config.json

  1. 添加此配置：
{
  "mcpServers": {
    "mcp_remote_exec": {
      "command": "uv",
      "args": ["run", "mcp-remote-exec"],
      "env": {
        "I_ACCEPT_RISKS": "true",
        "HOST": "192.168.1.100",
        "SSH_USERNAME": "root",
        "SSH_PASSWORD": "your_password"
      }
    }
  }
}
  1. 重新启动克劳德桌面

MCP工具

服务器为AI助手提供这些工具。

命令执行

  • ssh_exec_command -在远程服务器上执行bash命令

- 输出限制：默认情况下，结果被截断为25000个字符（可通过以下方式配置 CHARACTER_LIMIT) - 响应格式: - text：带有STDOUT、STDERR和退出代码部分的人类可读输出 - json：具有单独的stdout/stderr、截断标志和原始长度的结构化数据

文件操作

  • ssh_upload_file -将文件上传到远程服务器

- 默认行为：如果远程文件存在，则失败（设置 overwrite=true 替换） - 文件大小限制：默认情况下为10MB（可通过以下方式配置 MAX_FILE_SIZE) - 权限：使用八进制表示法设置文件权限的可选参数 - 指定为表示八进制值的十进制整数 - 例子： permissions=644 将文件设置为 rw-r--r-- （所有者读/写，组读，其他人读） - 例子： permissions=755 将文件设置为 rwxr-xr-x （所有者全部，组/其他人阅读+执行） - 例子： permissions=600 将文件设置为 rw------- （仅限所有者读/写）

  • ssh_download_file -从远程服务器下载文件

- 默认行为：如果本地文件存在，则失败（设置 overwrite=true 替换） - 文件大小限制：默认情况下为10MB（可通过以下方式配置 MAX_FILE_SIZE) - 安全：上传和下载默认为 overwrite=false 防止意外数据丢失

用法示例

命令执行示例

Check disk space: df -h
Show running processes: ps aux
Install packages: apt install nginx
View log files: tail -f /var/log/app.log
System information: uname -a

文件传输示例

Download log: /var/log/nginx/access.log to ./nginx.log
Upload config: ./config.yaml to /etc/app/config.yaml
Download backup: /backups/database.sql to ./backup.sql
Upload script: ./install.sh to /opt/scripts/install.sh

发展

运行测试

# Run unit tests
uv run pytest tests/ -v

# Run tests with coverage report
uv run pytest tests/ -v --cov=src/mcp_remote_exec --cov-report=term-missing --cov-report=html

# Using taskipy shortcuts
uv run task test         # Run all tests
uv run task test-cov     # Run tests with coverage

# Run in development mode
uv run mcp-remote-exec --help

# Test with local configuration
cp .env.example .env
# Edit .env with your test SSH server
uv run mcp-remote-exec

项目结构

src/mcp_remote_exec/
├── main.py                    # CLI entry point
├── common/                    # Layer 0: Common
│   ├── __init__.py
│   ├── constants.py           # Shared validation constraints
│   ├── enums.py               # Shared enumerations
│   └── validators.py          # Shared validators
├── config/                    # Layer 1: Configuration
│   ├── __init__.py
│   ├── constants.py           # Core application constants
│   ├── exceptions.py
│   └── ssh_config.py
├── data_access/               # Layer 2: Data Access
│   ├── __init__.py
│   ├── exceptions.py          # Domain-specific exceptions
│   ├── path_validator.py
│   ├── ssh_connection_manager.py
│   └── sftp_manager.py
├── services/                  # Layer 3: Services
│   ├── __init__.py
│   ├── command_service.py
│   ├── file_transfer_service.py  # Includes path validation wrapper
│   ├── file_utils.py          # Shared file operation utilities
│   └── output_formatter.py
├── presentation/              # Layer 4: Presentation
│   ├── __init__.py
│   ├── bootstrap.py           # Composition root (knows all layers)
│   ├── mcp_tools.py           # Core MCP tools
│   ├── models.py              # Input validation models
│   └── service_container.py   # Dependency injection container
└── plugins/                   # Extensions
    ├── base.py                # Plugin interface
    ├── registry.py            # Plugin discovery and registration
    ├── imagekit/              # ImageKit file transfer plugin
    │   ├── config.py          # Plugin configuration
    │   ├── constants.py       # Plugin-specific constants
    │   ├── imagekit_client.py # ImageKit API client
    │   ├── models.py
    │   ├── service.py
    │   ├── tools.py
    │   └── transfer_manager.py # Transfer state management
    └── proxmox/               # Proxmox container management plugin
        ├── config.py          # Plugin configuration
        ├── constants.py       # Plugin-specific constants
        ├── models.py
        ├── service.py
        └── tools.py

安全最佳实践

  1. 风险接受：始终设置 I_ACCEPT_RISKS=true 理解含义后
  2. 认证：尽可能使用SSH密钥而不是密码
  3. 访问控制：限制远程服务器上的SSH用户权限
  4. 监控：监控日志中的可疑活动
  5. 备份：在进行更改之前维护备份
  6. 指挥审查：执行前务必检查危险命令

故障排除

配置错误

No SSH host configuration found
  • 确保 .env 文件存在 HOST 集
  • 检查环境变量格式

身份验证错误

Authentication failed
  • 在中验证SSH凭据 .env
  • 检查远程服务器上的SSH用户权限
  • 手动测试SSH连接： ssh user@host

连接错误

SSH connection failed
  • 检查与远程服务器的网络连接
  • 验证SSH端口（默认22）是否打开
  • 检查防火墙规则

SSH密钥错误

SSH key file not found
  • 验证 SSH_KEY 环境变量指向现有的私钥文件
  • 检查文件路径是绝对路径还是相对于工作目录的正确路径
  • 确保密钥文件具有适当的权限（通常为600: -rw-------)
  • 测试密钥文件： ssh -i /path/to/key user@host
Failed to load private key
  • 密钥文件存在，但已损坏或格式不受支持
  • 支持的格式：RSA、Ed25519、ECDSA
  • Ed25519支持：需要Paramiko>=3.x才能获得Ed25519密钥支持。早期版本仅支持RSA和ECDSA
  • 测试密钥有效性： ssh-keygen -y -f /path/to/key
  • 如果密钥是用密码加密的，则必须先解密

主机密钥验证错误

Server 'hostname' not found in known_hosts

问题SSH主机的密钥不在known_hosts文件中，导致严格的主机密钥检查失败。

解决方案:

选项1：将主机添加到known_hosts（建议用于生产环境）

# On the system running mcp-remote-exec
ssh-keyscan -H your.server.com >> ~/.ssh/known_hosts

# For Docker containers, add to the container's known_hosts
docker exec container_name ssh-keyscan -H your.server.com >> /home/appuser/.ssh/known_hosts

选项2：禁用严格检查（方便开发/容器）

# In .env file
SSH_STRICT_HOST_KEY_CHECKING=false

何时使用每个选项:

  • 严格检查（真）：生产、安全关键环境
  • 自动接受（false）：开发、Docker容器、可信网络、频繁更换的主机

命令执行错误

Command execution timeout
  • 增加 TIMEOUT 开始 .env
  • 检查远程服务器是否响应
  • 验证命令不需要用户输入

贡献

欢迎投稿！请随时提交拉取请求。

许可证

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

支持

  • 问题:
  • 讨论:

致谢

______________________________________________________________________

由以下材料制成❤️ 面向MCP和SSH社区

⭐ 如果你觉得这很有用，请在存储库中加星！

目录标签

目录标签

PythonClaude系统管理SSH管理本地部署远程执行文件传输AI助手集成

支持客户端

Claude DesktopClaude

接入字段

传输方式（transport，传输协议）

stdio

鉴权方式（authType，认证方式）

none

运行时（runtime，运行环境）

Python

工具数量（toolCount，工具数）

11

资源数量（resourceCount，资源数）

0

提示词数量（promptCount，提示词数）

0

权限和风险

stdionone部署方式未说明

接入前请确认传输方式、认证方式和部署位置，并根据实际工具能力限制访问范围。

安装前确认

不要直接授予不必要的文件、网络或账号权限；先核对安装命令和配置内容。

来源信息

mcp-remote-exec logo

MCP World

mcpworld.com

/detail/148bde7b85ae2395e1c49f14074dd2f1

一个提供SSH访问远程服务器的MCP服务器，允许AI助手通过自然语言界面执行命令、传输文件和管理系统。

继续浏览同类 MCP

更多AI代理 MCP（18,706）返回 MCP 目录

上一个 MCP

MCP Remote Agent

Enables AI agents to remotely read/write files and execute commands on Linux servers via MCP protocol.

下一个 MCP

MCP Remote Macos Use F7fc8902

MCP Server是一个开源的远程macOS控制系统，允许AI完全控制远程macOS设备，无需额外软件安装，适用于自动化任务和AI代理操作。