Skip to main content
Glama
Sign In
deenesjakoruzh
SSH Remote File MCP Server

SSH Remote File MCP Server

by zhangqi-eiq
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SSH 远程文件 MCP 服务器

通过 Claude Code 读取、编辑并在远程服务器上运行命令——就像操作本地文件一样。

一个 MCP 服务器，将远程 SSH 主机暴露为一组文件系统工具。注册到 Claude Code 后，你可以让它读取 /home/you/proj/main.py、编辑某个函数、运行 pytest，或在整个远程目录树中执行 grep——它通过 SSH 与服务器通信，并带有路径作用域和命令过滤机制。

中文文档 / Chinese version → · GitHub →

许可证

MIT — 详见 LICENSE。

Related MCP server: claude-ssh-mcp

功能特性

工具

用途

ssh_read_file

读取远程文件

ssh_write_file

创建或覆盖（也可追加）远程文件

ssh_edit_file

在远程文件内部查找并替换

ssh_list_directory

列出远程目录（含权限、大小、修改时间）

ssh_run_command

在远程运行 shell 命令（带安全过滤）

ssh_search_files

按文件名通配符或内容查找文件

ssh_get_env_info

获取操作系统 / Python / 磁盘 / 内存 / CPU 快照

ssh_file_info

获取单个路径的详细状态信息

快速开始

# 1. Clone and enter
git clone https://github.com/zhangqi-eiq/server_mcp.git
cd server_mcp

# 2. Install (editable mode — picks up code changes immediately)
python install.py

# 3. Edit your real credentials
#    (file is at ~/.ssh-mcp-server/config.json by default)

# 4. Restart Claude Code, then in a chat:
#    "show me the env of my server"

就这样。install.py 会做三件事：

  1. pip install -e . — 安装软件包。

  2. 将 config.json（含占位值）复制到 ~/.ssh-mcp-server/。

  3. 运行 claude mcp add，让服务器出现在 Claude Code 中。

如果你还没有 claude 命令行工具，可以运行 python install.py --no-register，然后手动添加 MCP 条目（参见 手动配置）。

手动配置

如果你更愿意手动配置，或者 install.py 未能正确注册：

1. 安装软件包

pip install -e .

这样会将 ssh_mcp_server 放到 Python 的导入路径中，使得 python -m ssh_mcp_server 可以启动服务器。

2. 创建你的配置

将 config.json 复制到 ~/.ssh-mcp-server/config.json（当 SSH_MCP_CONFIG 未设置时，加载器会在此处查找），然后填入真实值：

mkdir -p ~/.ssh-mcp-server
cp config.json ~/.ssh-mcp-server/config.json
$EDITOR ~/.ssh-mcp-server/config.json

3. 注册到 Claude Code

MCP 条目必须通过你安装所用的 Python 解释器来调用服务器。下面的 <python> 应为该解释器的绝对路径（即你激活环境中的 sys.executable，例如 Windows 上的 C:\Users\you\.conda\envs\myenv\python.exe，或 Linux 上的 /home/you/.venv/bin/python）。

选项 A — 用户级作用域，适用于所有项目：

claude mcp add --scope user ssh-remote \
  -e SSH_MCP_CONFIG="$HOME/.ssh-mcp-server/config.json" \
  -- "<python>" -m ssh_mcp_server

选项 B — 项目级作用域，仅适用于当前项目：

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "ssh-remote": {
      "command": "<absolute path to python>",
      "args": ["-m", "ssh_mcp_server"],
      "env": {
        "SSH_MCP_CONFIG": "/absolute/path/to/your/config.json"
      }
    }
  }
}

注意：Claude Code 会在两个位置查找 mcpServers——~/.claude.json（由 claude mcp add 管理写入）和 ~/.claude/settings.json（手动编辑）。上面的 CLI 方式会自动写入正确的位置。

配置参考

config.json 的结构：

{
  "ssh": {
    "host": "your-server.example.com",
    "port": 22,
    "username": "your-username",
    "auth": {
      "type": "password",
      "key_path": "",
      "password": "your-password",
      "key_password": ""
    },
    "connect_timeout": 10,
    "keepalive_interval": 30
  },
  "allowed_paths": [
    "/home/your-username/projects"
  ],
  "security": {
    "blocked_commands": ["rm -rf /", "mkfs", ...],
    "max_file_size_mb": 50,
    "max_output_chars": 100000,
    "command_timeout": 30
  }
}

SSH 连接

字段

描述

默认值

ssh.host

服务器地址（IP 或域名）

必填

ssh.port

SSH 端口

22

ssh.username

登录用户名

必填

ssh.auth.type

"key" 或 "password"

"key"

ssh.auth.key_path

私钥路径（密钥认证）

当 type=key 时必填

ssh.auth.password

登录密码（密码认证）

当 type=password 时必填

ssh.auth.key_password

私钥的密码短语

空

ssh.connect_timeout

秒

10

ssh.keepalive_interval

心跳间隔（秒）

30

访问控制

  • allowed_paths — 远程目录白名单。所有文件操作在 .. 规范化后都会对照此列表进行校验。不在列表中的请求将被拒绝。子路径自动继承访问权限（例如 /data/proj 允许访问 /data/proj/sub/file.py）。

  • security.blocked_commands — ssh_run_command 拒绝执行的 shell 命令模式列表。默认值覆盖了常见的危险操作（rm -rf /、mkfs、shutdown、fork 炸弹、对块设备的原始写入）。你可以扩展此列表，但绝不应为了"修复"某个合理需求而削弱它——参见 安全模型。

资源限制

字段

效果

默认值

max_file_size_mb

ssh_read_file 拒绝读取超过此大小的文件

50

max_output_chars

ssh_run_command 将输出截断到此字符数

100000

command_timeout

ssh_run_command 超过此秒数后强制终止

30

认证方式

基于密钥（推荐）

# On your local machine
ssh-keygen -t ed25519 -C "you@example.com"

# Push the public key to the remote
ssh-copy-id -i ~/.ssh/id_ed25519.pub user@server

然后在 config.json 中：

"auth": {
  "type": "key",
  "key_path": "~/.ssh/id_ed25519",
  "key_password": ""
}

key_password 仅在私钥本身已加密时才需要填写。

基于密码

"auth": {
  "type": "password",
  "password": "your-password"
}

密码以明文形式存储在 config.json 中。建议优先使用密钥认证。

GUI 管理器（可选）

一个基于 Tk 的小型图形界面，可让你管理多个服务器配置并在它们之间切换：

# From source
python server_manager.py

# Or build a standalone Windows exe and put it on PATH
pip install -e ".[gui]"   # adds pyinstaller
python build.py
python setup_global.py
# now `SSH-Server-Manager` is on PATH

配置保存在 profiles.json 中；切换时会将所选配置复制到 config.json，这样 MCP 服务器会在下次启动时读取到它。

安全模型

该服务器在设计上刻意保持保守。有两层独立的机制保护远程主机：

  1. 路径作用域。 每个文件操作都会先进行规范化（解析 ..、合并斜杠），然后与 allowed_paths 对照检查。无法绕过此列表——检查是在远程端路径解析之后由服务器端执行的。

  2. 命令过滤。 ssh_run_command 会拒绝任何匹配 security.blocked_commands 的命令（子串匹配）。默认列表阻止了递归删除、对块设备的原始写入、系统关机、fork 炸弹以及远程 shell 安装器（curl … | sh）。如果你确实需要允许某些特定操作，可以扩展此列表——但不要削弱它。

该服务器不会做以下事情：

  • 不会以 root 身份在远程运行。请使用非 root 用户进行 SSH 连接。

  • 不会绕过 sudo。如果配置的用户无法 sudo，服务器同样无法执行。

  • 不提供交互式 shell。长时间运行的进程会被 command_timeout 强制终止。

故障排查

症状

可能原因

解决方法

claude mcp list 不显示任何内容

服务器注册到了错误的作用域，或 claude CLI 版本未读取 ~/.claude/settings.json

使用 claude mcp add --scope user ...（会写入 ~/.claude.json）

ModuleNotFoundError: No module named 'mcp'

安装到了与 claude 所使用的不同的 Python 环境中

使用你打算让 Claude Code 使用的解释器来运行 install.py

ERROR: ssh.host is required

配置中仍有占位值

编辑 ~/.ssh-mcp-server/config.json，替换 your-server.example.com、CHANGE_ME 等。

Access denied: outside allowed paths

LLM 尝试访问的路径不在 allowed_paths 中

将该路径添加到配置中的 allowed_paths

Command blocked: dangerous pattern

LLM 尝试执行了黑名单中的命令

如果确实需要，请调整 security.blocked_commands

SSH authentication failed

凭据错误或用户错误

在普通 shell 中用 ssh user@host 验证

服务器已启动但 Claude Code 不显示任何工具

VSCode 扩展进程已过期

完全退出并重新打开 VSCode

项目结构

server/
├── ssh_mcp_server/         # MCP server package (the actual product)
│   ├── server.py           #   tool definitions
│   ├── ssh_client.py       #   paramiko wrapper
│   ├── security.py         #   path + command validation
│   └── config.py           #   config loader
├── server_manager.py       # Tk GUI for managing profiles
├── profiles.json           # GUI profile store
├── config.json             # runtime config template (placeholder values)
├── setup.py                # pip-installable package metadata
├── install.py              # one-shot installer (install + register)
├── setup_global.py         # optional: deploy GUI exe to PATH
├── build.py                # optional: PyInstaller wrapper for the GUI
├── SSH-Server-Manager.spec # PyInstaller spec for fine-grained builds
├── requirements.txt        # raw dependency pins
├── LICENSE                 # MIT
├── README.md               # this file (English)
└── README.zh.md            # Chinese translation

许可证

MIT — 完整文本请参见该文件。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityStale
ResponsivenessNo recent community issues

Resources

Related MCP Connectors

Related MCP Servers

  • SSH Remote MCP Server

    nqmn
    A
    license
    A
    quality
    D
    maintenance
    Enables SSH remote access to servers through Claude, allowing users to execute commands, transfer files via SFTP, and manage multiple remote connections using natural language.
    12
    9
    MIT

  • MCP SSH Server

    austinzq
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    Enables Claude Code to control remote servers via SSH for automated deployment, testing, and operations, including command execution and file transfer.
    4
    -

  • SSH MCP Server

    quiloos39
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables Claude to execute commands on remote servers via SSH, with support for SSH config, private keys, password auth, and agent forwarding.
    70 npm
    ISC