SSH Remote File MCP Server

Читайте, редактируйте и выполняйте команды на удалённом сервере через Claude Code — как будто файлы находятся локально.

MCP-сервер, который предоставляет удалённый SSH-хост в виде набора файловых инструментов. После регистрации в Claude Code вы можете попросить его прочитать /home/you/proj/main.py, отредактировать функцию, запустить pytest или выполнить grep по удалённому дереву — при этом он общается с сервером по SSH, с ограничением путей и фильтрацией команд в процессе.

中文文档 / Китайская версия → · GitHub →

Лицензия

MIT — см. LICENSE.

Related MCP server: claude-ssh-mcp

Возможности

Быстрый старт

# 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.

Если у вас ещё нет CLI 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 из вашего активированного окружения, например C:\Users\you\.conda\envs\myenv\python.exe в Windows или /home/you/.venv/bin/python в Linux).

Вариант A — на уровне пользователя, доступен в любом проекте:

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

Вариант Б — на уровне проекта, только для этого проекта:

Создайте .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 (управляется CLI, записывается командой 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-подключение

Управление доступом

• allowed_paths — белый список удалённых каталогов. Каждая файловая операция проверяется по этому списку после нормализации ... Запросы за пределами списка отклоняются. Вложенные пути наследуют доступ (например, /data/proj разрешает /data/proj/sub/file.py).

• security.blocked_commands — список шаблонов shell-команд, которые ssh_run_command отказывается выполнять. По умолчанию покрыты очевидные опасные команды (rm -rf /, mkfs, shutdown, fork-бомбы, прямая запись в блочные устройства). Вы можете расширить список, но никогда не ослабляйте его, чтобы «решить» законную задачу — см. Модель безопасности.

Ограничения ресурсов

Аутентификация

По ключу (рекомендуется)

# 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. Предпочтительнее аутентификация по ключу.

Графический менеджер (необязательно)

Небольшой графический интерфейс на 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 на удалённой машине. Подключайтесь по SSH под обычным пользователем.

• Он не обходит sudo. Если у указанного пользователя нет прав sudo, то их нет и у сервера.

• Он не предоставляет интерактивную оболочку. Долго работающие процессы завершаются по command_timeout.

Устранение неполадок

Структура проекта

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 — полный текст см. в файле.