Bash MCP

Here is the translated Markdown document:

bash-mcp

Um servidor MCP (Model Context Protocol) simples que permite ao Claude executar comandos de shell sem prompts de permissão.

⚠️ Aviso de Segurança: Este servidor executa comandos de shell arbitrários. Use com cautela e apenas em ambientes confiáveis.

Instalação

# Install globally
npm install -g bash-mcp

# Or use with npx
npx bash-mcp

Início Rápido

Para o Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "bash": {
      "command": "npx",
      "args": ["bash-mcp"]
    }
  }
}

Para o Claude Code (Cursor, VS Code)

1. Abra a paleta de comandos (Cmd/Ctrl + Shift + P)
2. Execute "MCP: Add Server"
3. Selecione "NPM" como o tipo de servidor
4. Digite: bash-mcp

Ferramentas Disponíveis

run - Executa um comando

// Simple command
run("ls -la")

// With working directory
run("npm test", { cwd: "/path/to/project" })

// With timeout (milliseconds)
run("long-running-command", { timeout: 60000 })

run_background - Inicia um processo em segundo plano

// Start a dev server
run_background("npm run dev", "frontend")

// Start backend service with working directory
run_background("./gradlew bootRun", "backend", { cwd: "./backend" })

kill_background - Interrompe um processo em segundo plano

kill_background("frontend")

list_background - Lista todos os processos em segundo plano

list_background()

Exemplo de Uso

User: Start the development servers
Assistant: I'll start both frontend and backend servers for you.

[Uses run_background tool]
Started frontend server (PID: 12345)
Started backend server (PID: 12346)

User: Check if they're running
Assistant: [Uses list_background tool]
Both servers are running successfully!

Formato de Resposta

Todas as ferramentas retornam respostas formatadas em JSON:

{
  "success": true,
  "stdout": "command output",
  "stderr": "error output if any",
  "command": "executed command"
}

Para processos em segundo plano:

{
  "success": true,
  "name": "frontend",
  "pid": 12345,
  "command": "npm run dev",
  "message": "Started background process 'frontend' (PID: 12345)"
}

Recursos

• Executa qualquer comando de shell sem prompts de permissão
• Executa processos de longa duração em segundo plano
• Gerencia processos em segundo plano (listar, encerrar)
• Captura stdout e stderr
• Define o diretório de trabalho para comandos
• Configura timeout para comandos
• Limpeza automática ao encerrar o servidor
• NOVO: Truncamento automático de saída com saída completa salva em arquivos temporários
• NOVO: Limites de tamanho de saída configuráveis e diretório temporário via variáveis de ambiente

Variáveis de Ambiente

• BASH_MCP_MAX_OUTPUT_SIZE: Tamanho máximo de saída em bytes antes do truncamento (padrão: 51200/50KB)
• BASH_MCP_TEMP_DIR: Diretório para armazenar a saída completa quando truncada (padrão: diretório temporário do sistema)

Exemplo de Configuração

{
  "mcpServers": {
    "bash": {
      "command": "npx",
      "args": ["bash-mcp"],
      "env": {
        "BASH_MCP_MAX_OUTPUT_SIZE": "102400",
        "BASH_MCP_TEMP_DIR": "/tmp/bash-mcp-outputs"
      }
    }
  }
}

Tratamento de Estouro de Saída

Quando a saída do comando excede BASH_MCP_MAX_OUTPUT_SIZE:

1. A saída é truncada até o limite especificado
2. A saída completa é salva em um arquivo temporário
3. A resposta inclui o caminho do arquivo onde a saída completa pode ser encontrada
4. Se o diretório temporário personalizado falhar, ele volta para o diretório temporário do sistema

Considerações de Segurança

Este servidor MCP executa comandos de shell arbitrários com os mesmos privilégios do processo Node.js. Use apenas em ambientes de desenvolvimento ou contextos confiáveis.

Requisitos

• Node.js >= 16.0.0
• npm ou npx

Licença

MIT

Autor

tinywind tinywind0@gmail.com

Contribuição

Issues e pull requests são bem-vindos no GitHub.