mcp-shell-sudo

MCP-сервер для Linux, написанный на Python, который выполняет локальные команды через argv, поддерживает неинтерактивный sudo через PASSWORD_SUDO, предоставляет опциональный список разрешённых команд через ALLOW_COMMANDS и может ограничивать запись в файловую систему с помощью WORK_DIR и Bubblewrap.

Требования

• Linux.

• Python 3.11+.

• Рекомендуется uv.

• MCP Python SDK 2.0.0.

• sudo, если будут выполняться команды с повышенными привилегиями.

• bubblewrap, если настроен WORK_DIR.

В Debian/Ubuntu:

sudo apt update
sudo apt install -y bubblewrap

Related MCP server: MCP Process Server

Переменные окружения

PASSWORD_SUDO

Пароль пользователя, запускающего MCP-сервер.

• Пусто или не задано: сервер никогда не изобретает и не запрашивает пароль интерактивно. Команды с префиксом sudo выполняются с использованием sudo -n и будут работать только при наличии действительного кэшированного удостоверения или правила NOPASSWD.

• Задано: sudo выполняется с -S, и пароль передаётся через stdin, никогда через argv или журналы.

Пример:

"PASSWORD_SUDO": "my-password"

Поддерживаемая форма:

["sudo", "id"]

Пользовательские флаги sudo, такие как sudo -u postgres ..., не принимаются. Это предотвращает необходимость интерпретации полной грамматики команды sudo на уровне политики.

WORK_DIR

Необязательная рабочая директория.

• Пусто или не задано: MCP-сервер может работать из любой существующей директории, указанной в вызове инструмента.

• Задано: сервер переходит в строгий режим. directory должен разрешаться внутри WORK_DIR, и каждый процесс запускается в пространстве имён монтирования Bubblewrap, где / доступен только для чтения, WORK_DIR смонтирован для чтения и записи, а /tmp и /run являются временными.

Использование только cwd не было бы достаточным для гарантии такой изоляции. Процесс всё ещё мог бы записывать в /etc, /home/... или следовать по символическим ссылкам за пределы проекта. По этой причине сервер завершается с ошибкой при запуске, если WORK_DIR настроен, но bwrap недоступен.

В этом режиме sudo отклоняется, поскольку повышение привилегий на уровне хоста было бы несовместимо с гарантией того, что записи в файловую систему остаются ограниченными рабочим пространством.

ALLOW_COMMANDS

Список имён исполняемых файлов, разделённых запятыми.

"ALLOW_COMMANDS": "git,ls,cat,grep,python,node,pnpm"

• Пусто или не задано: разрешены все исполняемые файлы.

• Задано: разрешены только точные имена исполняемых файлов из списка, и они должны вызываться по имени, а не через пути, такие как /usr/bin/git.

• Если команда начинается с sudo, проверяется фактический исполняемый файл, следующий за sudo.

Список разрешённых применяется к исполняемым файлам, а не к аргументам. Разрешение bash, python, node, env или другого инструмента, способного выполнять процессы, значительно расширяет возможности MCP-клиента.

Установка

uv sync

Для разработки:

uv sync --extra dev

Ручной запуск

uv run mcp-shell-sudo

Транспорт — stdio. Журналирование никогда не записывается в stdout, чтобы не повредить JSON-RPC сообщения; журналы записываются в stderr.

Конфигурация MCP

Пример с неограниченными командами и включённым sudo:

{
  "mcpServers": {
    "shell": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "YOUR_PASSWORD",
        "WORK_DIR": "",
        "ALLOW_COMMANDS": ""
      }
    }
  }
}

Пример, ограниченный конкретным проектом:

{
  "mcpServers": {
    "shell-project": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/mcp-shell-sudo",
        "run",
        "mcp-shell-sudo"
      ],
      "env": {
        "PASSWORD_SUDO": "",
        "WORK_DIR": "/home/user/projects/app",
        "ALLOW_COMMANDS": "git,ls,cat,grep,find,python,node,pnpm"
      }
    }
  }
}

Инструмент shell_execute

Базовый ввод:

{
  "command": ["ls", "-la"]
}

С рабочей директорией:

{
  "command": ["git", "status"],
  "directory": "backend"
}

Со stdin:

{
  "command": ["cat"],
  "stdin": "hello\n"
}

С sudo:

{
  "command": ["sudo", "id"]
}

Ответ:

{
  "stdout": "uid=0(root) gid=0(root) groups=0(root)\n",
  "stderr": "",
  "status": 0,
  "execution_time": 0.031,
  "timed_out": false,
  "output_limited": false
}

Инструмент shell_config

Возвращает действующую несекретную конфигурацию.

Он никогда не возвращает PASSWORD_SUDO; он только указывает, был ли настроен пароль sudo.

Реализованные меры безопасности

• Использует create_subprocess_exec; не использует shell=True.

• command передаётся как явный массив argv.

• Пароль sudo никогда не появляется в argv, ответах, журналах или окружении дочернего процесса.

• Если PASSWORD_SUDO не настроен, sudo -n предотвращает зависание процесса в ожидании интерактивного запроса пароля.

• ALLOW_COMMANDS проверяет фактический исполняемый файл после простого вызова sudo.

• Использует фиксированный и сокращённый PATH, чтобы избежать поиска исполняемых файлов из . или произвольных унаследованных путей.

• Использует сокращённое окружение дочернего процесса вместо наследования всего окружения MCP-сервера.

• Тайм-аут на вызов: 60 секунд по умолчанию, максимум 600 секунд.

• Лимит вывода: 2 МиБ на поток. При превышении лимита вся группа процессов завершается.

• Процессы запускаются в новой сессии, и вся группа процессов завершается по тайм-ауту.

• WORK_DIR использует Bubblewrap и завершается с ошибкой, если изоляция не может быть обеспечена.

Важные ограничения

1. ALLOW_COMMANDS="" означает произвольное выполнение команд с правами пользователя, запускающего MCP-сервер. Если также настроен PASSWORD_SUDO, MCP-клиент может запрашивать действия от имени root. Используйте эту конфигурацию только с клиентом и моделью, которыми вы управляете.

2. Список разрешённых исполняемых файлов не проверяет семантически аргументы команд. python, node, bash, sh, perl и подобные инструменты фактически эквивалентны разрешению произвольного выполнения кода.

3. WORK_DIR ограничивает записываемые расположения файловой системы, но не предназначен для работы как виртуальная машина или сетевой песочница. Команда с доступом к сети может по-прежнему изменять удалённые ресурсы, для которых у неё есть действительные учётные данные.

4. PASSWORD_SUDO, хранящийся в конфигурации MCP-клиента, остаётся секретом, хранящимся в этом файле. Ограничьте права доступа к файлу с помощью chmod 600 и никогда не сохраняйте его в системе контроля версий.

Тесты

uv run --extra dev pytest
uv run --extra dev ruff check .