Ag Bash

@ag-bash/mcp-server

MCP server exposing 70 ag-bash tools to Claude Desktop and other MCP hosts

[npm version] [MCP Registry] [License: Apache-2.0]

A standalone Model Context Protocol (MCP) server that gives AI agents a persistent, sandboxed Bash environment, exposing 70 tools over stdio.

Installation

Add the server to Claude Code in one line:

claude mcp add ag-bash -- npx -y @ag-bash/mcp-server

Or install it globally:

npm install -g @ag-bash/mcp-server

Claude Code plugin

Install via the self-hosted marketplace:

/plugin marketplace add sairam0424/ag-bash/plugin install ag-bash@ag-bash

MCP Registry

Listed as io.github.sairam0424/ag-bash (active) at registry.modelcontextprotocol.io.

Also available via: Homebrew (ag-bash-mcp bin) · Docker MCP Catalog (in review)

brew tap sairam0424/tap && brew install ag-bash

Usage

Run the server directly:

npx ag-bash-mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Cursor / VS Code

Add a new MCP server in your IDE settings:

• Name: ag-bash
• Type: command
• Command: ag-bash-mcp

What's Exposed

• run_bash — Execute scripts with full unix toolkit (jq, grep, sed, awk, etc.)
• get_state — Inspect CWD, environment variables, and defined functions
• Agentic suite — ag-edit, ag-diff, ag-hover, ag-explain, ag-find-symbol, ag-todo, ag-analyze, ag-snapshot, ag-plan, ag-notebook, ag-mcp
• 70 tools total via JSON-RPC 2.0 with Zod schema validation on every input

Features

• Rate limiting — 60 requests/minute per session (configurable)
• Read-only root — Project files mounted as overlay; writes stay in memory
• Sanitized errors — JSON-RPC responses strip file paths, capped at 200 chars
• Zero console leakage — All diagnostics flow through structured handlers
• Resource limits — Protection against infinite loops and excessive memory
• Orchestration governance — Agent nesting limits prevent recursive loops

v4.1 Upgrade Notes

Links

• GitHub Repository
• Core Engine
• MCP Registry — io.github.sairam0424/ag-bash

License

Apache-2.0