A
licenseNot graded
qualityC
maintenanceEnables secure execution of shell commands through a dynamic approval system that prompts for user authorization on first use, with persistent command storage and comprehensive audit logging.
Apache 2.0
mcp-shell-sudo
by eaangrino
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 bubblewrapRelated MCP server: mcp-shell
Переменные окружения
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 и завершается с ошибкой, если изоляция не может быть обеспечена.
Важные ограничения
ALLOW_COMMANDS=""означает произвольное выполнение команд с правами пользователя, запускающего MCP-сервер. Если также настроенPASSWORD_SUDO, MCP-клиент может запрашивать действия от имени root. Используйте эту конфигурацию только с клиентом и моделью, которыми вы управляете.Список разрешённых исполняемых файлов не проверяет семантически аргументы команд.
python,node,bash,sh,perlи подобные инструменты фактически эквивалентны разрешению произвольного выполнения кода.WORK_DIRограничивает записываемые расположения файловой системы, но не предназначен для работы как виртуальная машина или сетевой песочница. Команда с доступом к сети может по-прежнему изменять удалённые ресурсы, для которых у неё есть действительные учётные данные.PASSWORD_SUDO, хранящийся в конфигурации MCP-клиента, остаётся секретом, хранящимся в этом файле. Ограничьте права доступа к файлу с помощьюchmod 600и никогда не сохраняйте его в системе контроля версий.
Тесты
uv run --extra dev pytest
uv run --extra dev ruff check .Available Tools
2 toolsshell_configA
Return the effective non-secret shell policy configuration.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A3.5/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description serves as the only behavioral disclosure. It implies a read-only operation ('Return') but does not explicitly state that it has no side effects or that it is safe. It does clarify that secrets are excluded, which is a useful constraint. However, it does not mention any authentication or permission requirements, which could be relevant.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the action ('Return') and specifies the resource. There is no wasted verbiage.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there are no parameters, the description sufficiently conveys the tool's function. The existence of an output schema covers return details, so the description need not elaborate. It does not mention usage context, but that is already addressed in usage_guidelines; for a simple config retrieval, this is complete enough.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the description is not required to explain parameter syntax. The phrase 'non-secret' adds context about the output scope but does not relate to parameters. For a parameterless tool, this is adequate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose4/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and a clear resource ('effective non-secret shell policy configuration'). It distinguishes itself from the sibling tool by nature (configuration retrieval vs. execution), though it does not explicitly name the alternative. The purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines2/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given for when to use this tool versus the sibling shell_execute. An agent must infer that this is for reading configuration, not executing commands. The description does not mention any prerequisites, alternatives, or context for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
shell_executeA
Execute one command as an argv array.
Args: command: Executable and arguments, for example ["ls", "-la"] or ["sudo", "systemctl", "status", "ssh"]. Shell syntax is not interpreted. stdin: Optional text sent to the command's standard input. directory: Optional working directory. With WORK_DIR configured, this path must resolve inside WORK_DIR. Without WORK_DIR, any existing directory may be used. timeout: Execution timeout in seconds. Values above 600 seconds are capped at 600.
Returns: stdout, stderr, exit status, execution time, timeout flag, and output-limit flag.
| Name | Required | Description | Default |
|---|---|---|---|
| stdin | No | ||
| command | Yes | ||
| timeout | No | ||
| directory | No |
Output Schema
| Name | Required | Description |
|---|---|---|
No output parameters | ||
TDQS
A4.2/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of disclosing behavioral traits. It mentions that shell syntax is not interpreted, that the timeout is capped at 600 seconds, and that directory paths must resolve inside WORK_DIR if configured. However, it does not warn about the potentially destructive nature of executing arbitrary commands or the side effects of the executed process, which is a notable omission for a command execution tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness4/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with a clear one-line summary, a detailed 'Args' section, and a 'Returns' section. It is appropriately detailed for a tool with multiple parameters but remains readable. The example for the command parameter adds clarity without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness4/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the essential invocation details: command format, directory constraints, timeout cap, and the return fields (stdout, stderr, exit status, etc.). It does not explain prerequisites such as the meaning of WORK_DIR, but this is likely a global configuration rather than tool-specific. Given the presence of an output schema (though not shown), the return-field listing is sufficient. Overall, it provides enough for an agent to call the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters5/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no descriptions for any of the four parameters (schema coverage 0%), so the description must fully compensate. It does so thoroughly by explaining each parameter: the command array with examples, optional stdin, directory restrictions relative to WORK_DIR, and timeout cap. This adds substantial meaning beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Execute one command as an argv array.' It clearly distinguishes from the sibling tool 'shell_config' by implying execution vs. configuration, and provides a concrete example to clarify the argv format.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides clear guidance on how to invoke the tool, including the requirement to pass an argv array rather than shell syntax, and clarifies timeout and directory constraints. However, it does not explicitly state when to prefer this tool over shell_config, though the purpose difference is evident from the name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
2 tool updates
v0.1.0- First observed
shell_config - First observed
shell_execute
TDQS
A3.9/5.0
Scored across 2 tools
Disambiguation5/5
The two tools have completely distinct purposes: one executes commands and the other returns configuration. There is no overlap or potential for misselection between them.
Naming Consistency5/5
Both tools follow the same snake_case verb_noun pattern (shell_execute, shell_config). The naming is clear, predictable, and consistent.
Tool Count3/5
With only two tools, this server feels thin, but the narrow scope (shell execution and configuration) justifies the limited surface. It is at the lower edge of what is reasonable, as stated in the calibration.
Completeness4/5
The tool surface covers the core functionality of executing shell commands and retrieving configuration. There is no obvious missing operation for the stated purpose; the only minor gap might be a way to list allowed commands or test, but that is not essential.
Maintenance
ActivityStale
ResponsivenessNo issues
Related MCP Connectors
Start, pause, resume, and run commands and file operations in Linux sandboxes.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Securely control computers you explicitly pair through files, terminals, processes, screenshots, desktop UI/input, clipboard, browser automation, diagnostics, and document tools.
Use a person's computer after they approve it there: files, Terminal, browser, local MCP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides a secure, token-authenticated command execution tool over MCP Streamable HTTP, with a default-deny allowlist and shell metacharacter rejection.11 npm1Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables controlled delegation of tasks to local coding-agent CLIs and the Manus API, with strict sandboxing, approval tracking, and remote-egress safeguards.4 npmMIT
sudo-proxyofficial
AlicenseAqualityAmaintenanceExecutes privileged commands with mandatory human approval via a TUI prompt, supporting local and remote execution through sudo.5MIT