ag-bash

Name: ag-bash
Author: sairam0424

Local

github.comDeveloper Tools1Updated 3d ago

Repository Visit website

About ag-bash

ag-bash is an MCP server for AI agents that provides a persistent, sandboxed Bash environment and code-intelligence tools. Its 70 tools include script execution, editing and analysis, with resource and nesting limits.

Key features

01Persistent sandboxed Bash environment
02Run scripts with Unix utilities
03Code editing, diffs, and analysis
04Inspect environment and functions
05Input validation and resource limits

Use cases

01Run shell scripts through an AI agent
02Review or edit project code
03Inspect the agent's shell environment

MCP support

Exposes 70 tools to MCP clients over stdio, including Bash execution, code operations, and environment inspection.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config

{
  "mcpServers": {
    "sairam0424-ag-bash": {
      "command": "npx",
      "args": [
        "-y",
        "@ag-bash/mcp-server"
      ]
    }
  }
}

Run commandnpx -y @ag-bash/mcp-server

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages

npm@ag-bash/mcp-server6.0.4stdio

Tools

Saved tool list · updated 3w ago

Parameter	Type	Required	Description
script	string	Yes	The bash script to execute.

Details

From the project README

@ag-bash/mcp-server

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

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

Before (v3.x)	After (v4.1)
6 tools	40+ tools
Basic bash execution	Full agentic suite with semantic code intelligence
Manual state management	Persistent environment across calls

License

Apache-2.0

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

Read the getting-started guide

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.