MCP Shell

mcp-shell

Servidor MCP que executa comandos de shell. Seu LLM recebe uma ferramenta; você tem controle sobre o que é executado e como.

Construído sobre mark3labs/mcp-go. Escrito em Go.

---

Execute

Docker (mais fácil):

docker run -it --rm -v /tmp/mcp-workspace:/tmp/mcp-workspace sonirico/mcp-shell:latest

A partir do código-fonte:

git clone https://github.com/sonirico/mcp-shell && cd mcp-shell
make install
mcp-shell

---

Configure

O modo seguro é o padrão. Sem arquivo de configuração, mcp-shell inicia em modo seguro e registra apenas ferramentas tipadas: leituras de arquivos, grep/glob, inspeção de git, e (opt-in) gravações de arquivos/git e scripts definidos pelo operador. Não há comando de shell bruto. Você só precisa de um arquivo de configuração para alterar os padrões abaixo. Para executar totalmente sem restrições, você deve optar explicitamente:

MCP_SHELL_ALLOW_UNSAFE=1 mcp-shell   # disables secure mode; the only tool is shell_exec

Para personalizar a política, aponte para uma configuração YAML:

export MCP_SHELL_SEC_CONFIG_FILE=/path/to/security.yaml
mcp-shell

Modo seguro (padrão) — apenas ferramentas tipadas, cada caminho confinado a working_directory:

security:
  enabled: true
  working_directory: /tmp/mcp-workspace
  max_execution_time: 30s
  max_output_size: 1048576
  run_as_user: ""
  audit_log: true

  # Expose file and git write tools (write_file, edit_file, mkdir, move,
  # delete, git_add, git_commit, git_switch, git_restore, git_stash). Off by
  # default.
  writes_enabled: false

  # Operator-defined scripts exposed through the run_script tool. The client
  # picks a name; the argv is yours and cannot be altered.
  # scripts:
  #   test: ["go", "test", "./..."]
  #   lint: ["golangci-lint", "run"]

---

Conecte

Claude Desktop — adicione à sua configuração MCP:

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "sonirico/mcp-shell:latest"],
      "env": { "MCP_SHELL_LOG_LEVEL": "info" }
    }
  }
}

Para configuração personalizada, monte o arquivo e defina a variável de ambiente:

{
  "command": "docker",
  "args": ["run", "--rm", "-i", "-v", "/path/to/security.yaml:/etc/mcp-shell/security.yaml", "-e", "MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/security.yaml", "sonirico/mcp-shell:latest"]
}

---

Ferramentas

O modo seguro (o padrão) registra estas ferramentas tipadas. * marca um parâmetro obrigatório.

Ferramenta	Parâmetros	Disponível
read_file	path*, offset, limit, tail	sempre
list_dir	path, depth, include_hidden	sempre
glob	pattern*, path, newer_than, max_results	sempre
grep	pattern*, path, glob, ignore_case, context, files_only, count, max_results	sempre
stat	path*	sempre
diff_files	path_a*, path_b*	sempre
system_info		sempre
git_status		sempre
git_log	max_count, ref, path, author, grep, since, until, oneline, follow	sempre
git_diff	ref, ref_to, staged, path, stat_only, name_only	sempre
git_show	ref, path, stat_only	sempre
git_blame	path*, ref, line_start, line_end	sempre
git_branches	all, merged	sempre
git_tags	pattern	sempre
git_rev_parse	ref*	sempre
git_ls_files	path, untracked	sempre
git_stash_list		sempre
git_remotes		sempre
write_file	path*, content*, append	writes_enabled
edit_file	path*, old_string*, new_string*, replace_all	writes_enabled
mkdir	path*	writes_enabled
move	from*, to*	writes_enabled
delete	path*, recursive	writes_enabled
git_add	paths, all	writes_enabled
git_commit	message*, all	writes_enabled
git_switch	branch*, create	writes_enabled
git_restore	paths*, staged	writes_enabled
git_stash	action*, message	writes_enabled
run_script	name*	scripts

Cada parâmetro de caminho é resolvido em relação a working_directory (symlinks seguidos); qualquer coisa fora disso é rejeitada. Caminhos e refs de git são passados posicionalmente e validados: um ref que começa com - é rejeitado. Não há ferramentas de rede; push, fetch e clone não são oferecidos.

Modo sem restrições: shell_exec existe apenas com MCP_SHELL_ALLOW_UNSAFE=1, executa o comando através de bash -c sem validação, por design, e é a única ferramenta registrada nesse modo.

---

Variáveis de ambiente

Variável	Descrição
MCP_SHELL_SEC_CONFIG_FILE	Caminho para o YAML de segurança (substitui os padrões seguros integrados)
MCP_SHELL_ALLOW_UNSAFE	Defina 1 (ou true) para desativar o modo seguro e expor shell_exec em vez das ferramentas tipadas (opt-in)
MCP_SHELL_SERVER_NAME	Nome do servidor (padrão: "mcp-shell 🐚")
MCP_SHELL_LOG_LEVEL	debug, info, warn, error, fatal
MCP_SHELL_LOG_FORMAT	json, console
MCP_SHELL_LOG_OUTPUT	stdout, stderr, file

---

Desenvolvimento

make install dev-tools   # deps + goimports, golines
make fmt test lint
make docker-build       # build image locally
make release            # binary + docker image

---

Segurança

• Padrão: Modo seguro. O servidor constrói o argv de cada comando por conta própria; o cliente nunca fornece uma string de shell. Apenas ferramentas tipadas são registradas.
• Confinamento de caminho: cada parâmetro de caminho é resolvido em relação a working_directory, symlinks seguidos, e qualquer coisa que resolva para fora dele é rejeitada.
• Endurecimento de git: caminhos são passados após --, refs após --end-of-options, e um ref que começa com - é rejeitado. O git é executado com GIT_CONFIG_NOSYSTEM=1, GIT_CONFIG_GLOBAL=/dev/null, core.fsmonitor, core.pager e core.hooksPath neutralizados, e --no-ext-diff --no-textconv em log/diff/show/blame.
• Ambiente mínimo: processos filhos recebem apenas PATH, HOME e LANG, nunca o ambiente do próprio servidor ou segredos de .env.
• Gravações e scripts são opt-in: writes_enabled: true expõe as ferramentas de gravação de arquivos/git; um mapa scripts não vazio expõe run_script. Ambos estão desativados por padrão.
• Sem restrições: apenas via MCP_SHELL_ALLOW_UNSAFE=1. A única ferramenta registrada é shell_exec, que executa bash -c sem validação. Adequado para desenvolvimento local, perigoso caso contrário.
• Docker: Executa como não-root, baseado em Alpine. Use em produção. Melhor combinado com um sandbox de SO (sistema de arquivos somente leitura, capacidades removidas) como defesa em profundidade.

O modelo de ameaças, garantias e o escopo para relatórios de vulnerabilidades estão em SECURITY.md. Leia antes de abrir um advisory.

---

Migrando da versão 0.x

O modo seguro não valida mais uma string de comando shell_exec; ele expõe ferramentas tipadas em vez disso. O bloco security: de um arquivo de configuração não aceita mais:

Chave removida	Substituição
use_shell_execution	não é necessário; ferramentas tipadas nunca fazem shell out
allowed_executables	não é necessário; cada ferramenta executa um argv fixo construído pelo servidor
allowed_commands	não é necessário; igual ao acima
blocked_commands	não é necessário; igual ao acima
blocked_patterns	não é necessário; igual ao acima

Carregar um arquivo de configuração que ainda define um desses falha na inicialização com um erro nomeando a chave. Não há mais "modo legado" e nenhum exemplo de security-legacy.yaml. Se você precisar de acesso bruto ao shell, defina MCP_SHELL_ALLOW_UNSAFE=1 para obter shell_exec de volta; ele não é mais restringido pelo bloco security: de forma alguma.

---

Contribuindo

Faça um fork, crie um branch, make fmt test, abra um PR.