Bash MCP

A simple MCP (Model Context Protocol) server that enables Claude to execute shell commands without permission prompts.

⚠️Security Warning: This server executes arbitrary shell commands. Use with caution and only in trusted environments.

# Install globally npm install -g bash-mcp # Or use with npx npx bash-mcp

Add to yourclaude_desktop_config.json:

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

- Open command palette (Cmd/Ctrl + Shift + P)
- Run "MCP: Add Server"
- Select "NPM" as the server type
- Enter:bash-mcp

// 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- Start a background process

// 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- Stop a background process

list_background- List all background processes

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!

All tools return JSON formatted responses:

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

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

- Execute any shell command without permission prompts
- Run long-running processes in the background
- Manage background processes (list, kill)
- Capture stdout and stderr
- Set working directory for commands
- Configure timeout for commands
- Automatic cleanup on server shutdown
- NEW: Automatic output truncation with full output saved to temp files
- NEW: Configurable output size limits and temp directory via environment variables

- BASH_MCP_MAX_OUTPUT_SIZE: Maximum output size in bytes before truncation (default: 51200/50KB)
- BASH_MCP_TEMP_DIR: Directory for storing full output when truncated (default: system temp directory)

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

When command output exceedsBASH_MCP_MAX_OUTPUT_SIZE:
- Output is truncated to the specified limit
- Full output is saved to a temporary file
- The response includes the file path where full output can be found
- If custom temp directory fails, falls back to system temp directory

This MCP server executes arbitrary shell commands with the same privileges as the Node.js process. Only use in development environments or trusted contexts.

Issues and pull requests are welcome atGitHub.

Execute terminal commands through a secure shell interface using an AI assistant.