bash-mcp

bash-mcp is a local stdio MCP server that gives an MCP client unrestricted access to execute local Bash commands with your user account.

Every bash_exec call explicitly sources ~/.profile and ~/.bashrc before running the requested command. The server also exposes list_bash_executables so a client can discover and select from the Bash binaries available on the machine.

This project is intentionally unsandboxed. If you attach it to an LLM client, that client can run arbitrary local commands as you.

What It Does

• Runs as a stdio MCP server using the official MCP Node SDK
• Enumerates discoverable Bash binaries on macOS and Linux
• Executes commands with optional cwd, env, timeout_seconds, and bash_executable
• Sources ~/.profile and ~/.bashrc on every command
• Installs into multiple MCP clients with one script

Supported Clients

• Codex
• Claude Code
• Claude Desktop
• Cursor
• Augment
• GitHub Copilot CLI
• GitHub Copilot in VS Code

Requirements

• macOS or Linux
• node 18+
• npm

Security Model

There is no allowlist, approval gate, or runtime sandbox in this server.

If a client can call bash_exec, it can:

• read and modify files your user can access
• start processes
• use networked tools already available on your machine
• inherit environment set by ~/.profile and ~/.bashrc

Do not install this into clients or environments you do not trust.

Install

Interactive install:

./install.sh

Install into selected clients:

./install.sh --tool codex,claude,claude-desktop

Install everywhere the script detects a supported client:

./install.sh --all-found

Dry run:

./install.sh --tool cursor,copilot-cli --dry-run

The installer stages the runtime under:

• ~/.local/share/bash-mcp/
• ~/.local/bin/bash-mcp-server

Client Notes

• codex Uses codex mcp add.
• claude Uses claude mcp add --scope user.
• claude-desktop Writes claude_desktop_config.json. On macOS this is ~/Library/Application Support/Claude/claude_desktop_config.json.
• cursor Writes ~/.cursor/mcp.json.
• augment Writes ~/.augment/settings.json.
• copilot-cli Writes ~/.copilot/mcp-config.json.
• copilot-vscode Writes the default user MCP config for VS Code.

Claude Desktop requires a full quit and relaunch after config changes.

Tools

list_bash_executables

Arguments: none.

Returns executables, where each entry contains:

• path
• realpath
• version
• is_default

Discovery covers Bash binaries visible on PATH plus common system bin directories. Results are deduplicated by resolved realpath, and only executables that identify as Bash are returned.

bash_exec

Arguments:

• command required
• bash_executable optional
• cwd optional
• env optional
• timeout_seconds optional, default 120

Returns:

• stdout
• stderr
• exit_code
• timed_out
• duration_ms
• bash_executable
• bash_realpath
• cwd
• loaded_init_files
• stdout_truncated
• stderr_truncated

Command Execution Semantics

For each bash_exec call, the server:

1. selects the requested Bash binary, or the first discovered Bash
2. starts Bash with --noprofile --norc
3. sources ~/.profile if readable
4. sources ~/.bashrc if readable
5. applies the provided environment overrides
6. changes into cwd if provided
7. evaluates the command string

This keeps behavior consistent across clients, even when they launch the MCP server from a GUI process with a minimal environment.

Local Development

Install dependencies:

npm install

Run tests:

npm test

Smoke-check the installer:

./install.sh --all-found --dry-run

Launch the server directly:

./bash_mcp.sh

Uninstall

Remove the client config entries that reference bash-mcp, then remove the staged files:

rm -rf ~/.local/share/bash-mcp
rm -f ~/.local/bin/bash-mcp-server

Repository

GitHub: https://github.com/davidjbeveridge/bash-mcp