bash-mcp

Fast, secure MCP server that gives an AI agent controlled access to the local filesystem and bash.

Tools

| Tool | Description | |------|-------------| | read_file | Read a file (text or binary). Supports line offset/limit. | | write_file | Create or overwrite a file. Parent dirs are created automatically. | | update_file | Apply targeted edits: string replacement or line insertion. | | delete_file | Delete a file or directory (directories require recursive: true). | | bash | Run an arbitrary bash command. Configurable timeout. |

Quick start

bun install
bun run src/index.ts   # stdio transport — connect with any MCP client

Claude Desktop / Claude Code integration

Add to your MCP config (e.g. ~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "bash-mcp": {
      "command": "bun",
      "args": ["/absolute/path/to/bash-mcp/src/index.ts"]
    }
  }
}

Security

Path restriction (recommended)

Set ALLOWED_DIRS to a colon-separated list of directories the agent may access. Paths outside these roots are rejected, including symlink-resolved paths.

ALLOWED_DIRS="/home/user/projects:/tmp" bun run src/index.ts

Leaving ALLOWED_DIRS unset grants full filesystem access (use with trusted agents only).

Disable bash

BASH_DISABLED=true bun run src/index.ts

Environment variables

| Variable | Default | Description | |----------|---------|-------------| | ALLOWED_DIRS | (unset) | Colon-separated allowed root directories. Empty = unrestricted. | | MAX_FILE_SIZE_MB | 50 | Maximum file size for read/write operations. | | BASH_DISABLED | false | Set to "true" to disable the bash tool entirely. | | BASH_TIMEOUT_MS | 30000 | Bash command timeout in milliseconds. | | BASH_MAX_OUTPUT_MB | 5 | Maximum combined stdout+stderr from bash. |

MCP Servers