Skip to main content
Glama

bash-mcp

An MCP server that wraps common CLI tools (kubectl, terraform, helm, git, argocd, jq, yq, ripgrep, etc.) and returns structured JSON instead of raw text output.

Designed for AI agents and LLM-powered workflows where parsing human-readable CLI output wastes tokens and breaks easily.

Created with the help of Claude since it is the main consumer of the structured data.

Quick Start

Option 1: Zero-install with npx

No installation needed — just add the MCP config and npx will fetch it on first use.

Option 2: Global install

npm install -g @nickw8/bash-mcp

Option 3: Install from source

git clone https://github.com/nickw8/bash-mcp.git
cd bash-mcp
npm install && npm run build
npm link

Related MCP server: Pare

Verify your setup

Run the built-in preflight check before wiring bash-mcp into a client:

npx -y @nickw8/bash-mcp --doctor   # or: bash-mcp --doctor (global install)

It reports your Node version, whether the MCP SDK loads, which CLIs are available (versions included), and the resolved BASH_MCP_MODE — then exits non-zero if a critical check fails (Node too old or the SDK can't load). Missing CLIs are advisory, not failures. Without --doctor, the binary starts the MCP server as usual.

Claude Code Setup

Add bash-mcp to your Claude Code settings. For all projects (recommended), edit ~/.claude/settings.json. For a single project, edit .claude/settings.json in the project root.

With npx (no install required):

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

Safe by default: an unset BASH_MCP_MODE resolves to readOnly, which blocks mutating run/batch commands. The examples set it explicitly for clarity. For trusted local use, set BASH_MCP_MODE=off to allow writes.

With global install:

{
  "mcpServers": {
    "bash-mcp": {
      "command": "bash-mcp",
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

To verify it's working, start Claude Code and check that bash-mcp tools (like cat, rg, git_status) appear in the tool list.

You can also add it from the CLI:

claude mcp add bash-mcp -e BASH_MCP_MODE=readOnly -- npx -y @nickw8/bash-mcp

Steer agents toward the structured tools (optional)

Registering the server exposes the tools, but agents still reach for raw Bash out of habit. Two assets fix that: a rules file (~/.claude/rules/bash-mcp-tools.md, auto-loaded into every session — the tool inventory) and a PreToolUse(Bash) redirect hook. Install both with:

npx -y @nickw8/bash-mcp --install-claude        # copy into ~/.claude
npx -y @nickw8/bash-mcp --install-claude --check # report drift, write nothing

It prints the settings.json hook block to paste in (the rules file needs no settings — Claude Code auto-loads ~/.claude/rules/*.md). See hooks/README.md for details and the clone-time npm run claude:install equivalent. --uninstall-claude removes both files again.

Or install the Claude Code plugin, which bundles the server and the hook (in warn mode — it never blocks unless BASH_MCP_HOOK=block):

/plugin install bash-mcp --marketplace nickw8/bash-mcp

Every other client (VS Code/Copilot, Codex, generic stdio) and pinned versions: docs/guides/installation.md.

Claude Desktop Setup

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and add the same mcpServers entry:

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

Restart Claude Desktop after editing.

Cursor Setup

Add bash-mcp to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per-project):

{
  "mcpServers": {
    "bash-mcp": {
      "command": "npx",
      "args": ["-y", "@nickw8/bash-mcp"],
      "env": {
        "BASH_MCP_MODE": "readOnly"
      }
    }
  }
}

(Use "command": "bash-mcp" with no args if you installed globally.) Any MCP-aware client works the same way — point it at the bash-mcp binary or npx -y @nickw8/bash-mcp.

Optional Claude Code hooks in hooks/ steer agents toward the structured tools by blocking raw shell commands (git status, kubectl get, cat, …) that have a bash-mcp equivalent, while letting write commands (git commit, kubectl apply) pass through. BASH_MCP_HOOK=warn makes every block advisory; off disables the hook.

See docs/runbooks/hooks-setup.md for setup.

Why Structured Output?

Raw CLI tools return text meant for humans. AI agents waste tokens parsing tables, aligning columns, and guessing field boundaries. bash-mcp runs the same CLI tools but returns structured JSON with typed schemas, so the agent gets exactly the data it needs.

# Raw kubectl output: 148 tokens to parse a table
NAME                     READY   STATUS    RESTARTS   AGE
nginx-7c5b8d6c88-abc12  1/1     Running   0          3d

# bash-mcp output: typed, compact, ready to use
{ "name": "nginx-7c5b8d6c88-abc12", "status": "Running", "age": "3d", ... }

See docs/guides/token-benchmarks.md for measured savings (e.g. kubectl describe pod → kube_diagnose_pod is ~64% fewer tokens).

Philosophy: structured tools first, run is the escape hatch

  1. Reach for a structured tool first. Every wrapper returns typed JSON the agent can use directly — no column-counting, no re-parsing on a format change.

  2. Prefer a diagnostic over a chain of raw commands. Tools like kube_diagnose_pod, helm_release_triage, and argo_app_health_summary answer an operational question in one call — { status, likelyCauses, suggestedNextCommands, evidence } — instead of making the agent run get, then logs, then reason across both.

  3. run / batch are the escape hatch. For commands without a dedicated wrapper, run executes anything with smart truncation. Optional hooks actively steer agents back to the structured tool when a raw equivalent is invoked.

Read-only tools carry the MCP readOnlyHint annotation. run/batch can be gated with BASH_MCP_MODE (see Configuration).

Which tool should I use?

Pick the structured tool that matches your intent instead of reaching for a raw command. The list_guidance tool returns this same index as JSON (filter by intent or category), so agents can self-select without the README.

I want to…

Use this

Instead of

diagnose a crashing or failing Kubernetes pod

kube_diagnose_pod

kubectl describe pod, kubectl logs

find all not-ready or failing pods in a namespace

kube_pod_failure_summary

kubectl get pods, kubectl get pods | grep

check a deployment's rollout health

kube_deployment_status

kubectl rollout status, kubectl get deployment

understand recent cluster events

kube_events_summary

kubectl get events

summarize the changes in a Terraform plan

tf_plan_summary

terraform plan, terraform show

review the current feature branch before a PR

git_pr_context

git diff, git log, git status

understand the overall state of a repository

repo_health_summary

git status, git log --oneline

read a file's structure without loading the full body

outline

cat (entire file), cat

read one region of a large file

cat

cat (whole file), sed -n '10,40p'

keep a broad search from flooding the context

rg

rg | head

search for exact code references or symbols

rg

grep -r, rg

check whether a pull request's CI checks pass

gh_pr_checks

gh pr checks, gh pr view

find out why a CI / GitHub Actions run failed

gh_run_failure_summary

gh run view --log-failed, gh run list

check whether a GitLab pipeline or merge request's jobs pass

glab_ci_status

glab ci get, glab ci status

find out why a GitLab CI pipeline failed

glab_pipeline_failure_summary

glab ci trace, glab ci view

triage why a Helm release is unhealthy

helm_release_triage

helm status, helm get values

check whether an ArgoCD app is healthy and in sync

argo_app_health_summary

argocd app get, argocd app list

validate a Liquibase changelog for errors

liquibase_validate

liquibase validate

preview the SQL Liquibase would run for pending changesets

liquibase_update_sql

liquibase updateSQL, liquibase updateSQL | grep

list Liquibase changesets not yet applied to the database

liquibase_status

liquibase status --verbose

lint a shell script for bugs and quoting issues

bash_lint

shellcheck, shellcheck -f json1

run a bats or shell test suite

bash_test

bats, bash test.sh

discover which CLIs are installed before calling a tool

check_environment

which, <tool> --version

Tools

📖 Full tool reference → docs/tools.md — generated from the registered tools (inputs, outputs, and the raw command each one approximates). Regenerate with npm run docs:tools.

Environment

Tool

Description

check_environment

Report which CLIs are installed (and their versions) so you can pick the right tool before calling it.

list_guidance

Return an intent → preferred-tool index so you can pick the right bash-mcp tool for a goal.

Filesystem

Tool

Description

ls

List files in a directory.

tree

Show directory structure as a compact tree.

du

Show disk usage for paths.

find_files

Find files by name pattern, type, or modification time.

Tool

Description

rg

Search file contents with ripgrep.

glob

Find files matching a glob pattern.

File

Tool

Description

cat

Read one or more files with line numbers and smart truncation.

outline

Show the structural outline of a file — function/class names, top-level comments, imports.

Git

Tool

Description

git_status

Structured git status: branch, staged/unstaged/untracked files.

git_log

Structured git log: commit hash, author, date, message.

git_diff

Structured git diff: files changed with insertions/deletions counts.

git_branches

List git branches.

repo_health_summary

One-call snapshot of a git working tree: branch, ahead/behind vs upstream, staged/unstaged/untracked counts, recent commits, and the uncommitted diffstat.

git_pr_context

Collect the commits and file changes of a branch vs a base ref (for writing a PR description): commit list, changed files with status, and a diffstat over base...head.

git_diff_content

Show git diff with structured patch content.

GitHub

Tool

Description

gh_pr_checks

Report a pull request's CI checks as counts per state plus the failing and pending checks.

gh_run_failure_summary

Diagnose a GitHub Actions run in one call: status, the failed jobs and steps, and the ##[error] lines from the failed log as evidence.

GitLab

Tool

Description

glab_ci_status

Report a GitLab pipeline's jobs as counts per status plus the failed, running and pending jobs.

glab_pipeline_failure_summary

Diagnose a GitLab pipeline in one call: status, the failed jobs and why GitLab says they failed, and the last script lines of each failed job's trace as evidence.

Kubernetes

Tool

Description

kube_get

Get Kubernetes resources as structured data.

kube_logs

Get pod logs.

kube_contexts

List available kubectl contexts with current context marked.

kube_diagnose_pod

Diagnose why a pod is unhealthy in one call.

kube_pod_failure_summary

List unhealthy pods in a namespace with their failure reason and evidence — one call instead of get + describe per pod.

kube_deployment_status

Report a deployment's rollout health (ready/desired replicas, conditions) as a structured diagnosis.

kube_events_summary

Summarize Warning events in a namespace (grouped by reason, ordered by count) instead of scrolling raw kubectl get events.

Terraform

Tool

Description

tf_state_list

List resources in Terraform state.

tf_show

Show current Terraform state as structured JSON.

tf_plan_summary

Run terraform plan and return a structured summary of changes (add/change/destroy counts and affected resources).

tf_workspaces

List Terraform workspaces with current workspace marked.

tf_outputs

List Terraform/OpenTofu outputs as [name, value] pairs; a sensitive output is redacted to [name] alone.

tf_providers

List the Terraform/OpenTofu version and selected provider versions for the project.

tf_validate_summary

Validate the Terraform/OpenTofu config and return a compact pass/fail summary with diagnostics.

tf_modules_summary

List the modules used by an initialized Terraform/OpenTofu project (key, source, version).

tf_backend_info

Report the configured backend type and config for an initialized project.

Helm

Tool

Description

helm_list

List Helm releases with status, chart, and app version.

helm_status

Get detailed status of a Helm release.

helm_values

Get the computed values for a Helm release as structured data.

helm_release_triage

Diagnose a Helm release's health in one call: combines helm status + helm history into current status, likely causes, suggested next commands, and recent-revision evidence.

ArgoCD

Tool

Description

argo_apps

List ArgoCD applications with sync/health status.

argo_app_detail

Get detailed status for a single ArgoCD application including resource health.

argo_app_diff

Show what's out of sync for an ArgoCD application.

argo_app_health_summary

Diagnose an ArgoCD application's health in one call: overall sync/health, likely causes, suggested next commands, and the unhealthy resources/conditions as evidence.

Data Processing

Tool

Description

jq

Query and transform JSON using jq expressions.

yq

Query and transform YAML files using yq expressions (mikefarah/yq).

.NET

Tool

Description

dotnet_build

Run dotnet build and return structured diagnostics with file, line, column, message, and error code.

dotnet_test

Run dotnet test and return structured results: pass/fail/skip counts, failure messages.

Liquibase

Tool

Description

liquibase_validate

Validate a Liquibase changelog and return a structured pass/fail result with per-changeset errors (duplicate ids, checksum drift).

liquibase_update_sql

Render the SQL Liquibase would run for pending changesets (updateSQL) as structured per-changeset summaries with a SQL-Server batch lint.

liquibase_status

List Liquibase changesets not yet applied to the target database, as structured JSON.

Node.js

Tool

Description

npm_lint

Run biome check and return structured diagnostics with file, line, column, message, and rule.

npm_test

Run vitest or jest (picked from package.json) and return structured test results: suites, pass/fail counts, failure messages.

npm_typecheck

Run tsc/tsgo --noEmit and return structured type errors with file, line, column, message, and TS error code.

Python

Tool

Description

python_lint

Run ruff check and return structured diagnostics with file, line, column, message, and rule code.

python_test

Run pytest and return structured test results: suites, pass/fail counts, failure messages.

python_typecheck

Run mypy and return structured type errors with file, line, column, message, and error code.

Shell

Tool

Description

bash_syntax_check

Check shell scripts for syntax errors with bash -n and return structured diagnostics (file, line, message).

bash_lint

Run shellcheck and return structured diagnostics with file, line, column, message, and SC rule code.

bash_test

Run a shell test script — bats .bats files via --tap, or a plain .sh harness — and return structured results: per-case pass/fail plus a summary parsed from TAP or N tests, M failures output, falling back to exit-code-only when the format is unrecognized.

Execution

Tool

Description

run

Run a single command — a binary plus an args array, executed directly without a shell (so no pipes, redirects, or ';'/'&&' in the string) — and return structured output with smart truncation.

run_seq

Run an ordered list of labeled commands one after another, stopping at the first failure by default.

batch

Run multiple commands in parallel and return all results.

Results

Tool

Description

result_get

Page through a result the response budget trimmed.

All tf_* tools accept binary: "terraform" | "tofu" (or set $TF_BINARY) to run OpenTofu.

Example Agent Workflows

Triage a crash-looping pod. Before — three raw calls plus reasoning:

kubectl get pods -n payments          # find the broken pod
kubectl describe pod api-xyz          # read events/state, infer cause
kubectl logs api-xyz --tail=200       # scroll for the error
# ...agent reasons across all three to guess the next step

After — one structured call:

kube_diagnose_pod(pod="api-xyz", namespace="payments")
→ { status: "CrashLoopBackOff",
    likelyCauses: ["container exits 1; DB connection refused"],
    suggestedNextCommands: ["kube_logs(pod='api-xyz', container='api')"],
    evidence: ["Restart Count: 12", "BackOff x140 over 30m"] }

Review a feature branch. Before: git log main..HEAD, git diff --stat main...HEAD, git diff main...HEAD — three commands, manual stitching. After:

git_pr_context(base="main")
→ { commits: [...], files: [...], summary: { filesChanged, insertions, deletions } }

Check capabilities before acting. Instead of which kubectl && kubectl config current-context:

check_environment()
→ { kubectl: { installed: true, version: "1.31.2", context: "prod" },
    terraform: { installed: false }, ... }

Configuration

Environment Variables

Variable

Values

Default

Effect

BASH_MCP_LOG

error | info | off

error

Wide-event JSON logging to stderr (one line per tool call). error logs only failed calls; info adds successes; off/silent disables. stdout always stays pure MCP. run/batch commands are redacted (metadata only).

BASH_MCP_MODE

readOnly | confirmWrites | off

readOnly

Gates run/batch. Default readOnly blocks commands classified as mutating (confirmWrites likewise). Set off (or dangerous) to disable enforcement — recommended only for trusted local use.

BASH_MCP_PROFILE

core | development | infrastructure | all

all

Which tool groups register. Fewer tools, less schema in context — see tool discovery. An unknown value fails at startup.

BASH_MCP_RESPONSE_MODE

auto | summary | compact | full

auto

Response budget. A cut result carries retained and its full payload is pageable with result_get. full is the v4 behaviour. See output conventions.

BASH_MCP_RESULT_TTL

seconds

900

How long a stored result stays retrievable; 0 disables the store.

BASH_MCP_HOOK

block | warn | off

block (warn in the plugin)

Redirect hook behaviour.

TF_BINARY

terraform | tofu

terraform

Default binary for all tf_* tools (overridable per-call via binary).

Timeouts

Each tool group uses appropriate default timeouts:

  • Filesystem/search/git: 30 seconds

  • Kubernetes/Helm/ArgoCD: 15 seconds

  • Terraform state: 30 seconds

  • Terraform plan: 120 seconds

  • .NET build/test: 120 seconds

  • Python lint: 30 seconds

  • Python test: 120 seconds

  • Python typecheck: 60 seconds

Command Buffer

All commands default to a 10 MB output buffer. Override per-tool in src/exec.ts.

Development

# Install dependencies
npm install

# Run in development mode (auto-reloads)
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Run tests
npm test

# Lint and format
npm run lint
npm run format

Architecture

src/
  index.ts              # Server entry point — registers tools and starts stdio transport
  exec.ts               # Command execution layer — runs CLI tools via execFile
  tool.ts               # defineTool — wraps registerTool with wide-event logging + error catching
  error.ts              # ToolError taxonomy + classifyError (missing_binary, timeout, ...)
  logger.ts             # Zero-dep structured stderr logger (BASH_MCP_LOG)
  safety.ts             # Command classification + BASH_MCP_MODE gate for run/batch
  format.ts             # Multi-format list output (TSV, columnar, JSON)
  response.ts           # MCP response helpers (ok, okList, err)
  shell.ts              # Shell escaping utilities
  parsers/
    types.ts            # Shared interfaces: Diagnostic, TestResult, TestSuite
    schemas.ts          # Shared Zod (diagnostic, budget fragment, applyBudget)
  tools/
    argocd/argocd.ts    # argo_apps, argo_app_detail, argo_app_diff
    batch/batch.ts      # batch (parallel command execution)
    dotnet/
      dotnet.ts         # dotnet_build, dotnet_test
      parsers/          # MSBuild and TRX output parsers
    file/
      file.ts           # cat (file reading with metadata), outline (structural file outline)
      outline/          # Language-specific outline extractors
    filesystem/
      filesystem.ts     # ls, tree, du, find_files
    git/
      git.ts            # git_status, git_log, git_diff, git_branches
      diff.ts           # git_diff_content (structured patch hunks)
    helm/helm.ts        # helm_list, helm_status, helm_values
    json/json.ts        # jq
    kubernetes/
      kubernetes.ts     # kube_get, kube_logs, kube_contexts
    npm/
      npm.ts            # npm_lint, npm_test, npm_typecheck
      parsers/          # Biome, Vitest, tsc output parsers
    run/run.ts          # run (command execution with smart truncation)
    search/search.ts    # rg, glob
    terraform/
      terraform.ts      # tf_state_list, tf_show, tf_plan_summary, tf_workspaces
    yaml/yaml.ts        # yq

Each tool file exports a single register*Tools(server) function that registers all tools in its group. Every tool returns both content (text for display) and structuredContent (typed JSON for programmatic use).

Adding a New Tool

  1. Add to an existing category (src/tools/<group>/<group>.ts) or create a new category directory

  2. Define input/output schemas with Zod (add annotations: { readOnlyHint: true } for read-only tools)

  3. Implement the handler using exec() or execJson() from #exec, return ok() or err() from #response

  4. Register it with defineTool from #tool (injects wide-event logging + uniform error catching)

  5. Wire the group's register*Tools into src/index.ts

  6. Add tests in a co-located *.test.ts file

import { z } from "zod";
import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { exec } from "#exec";
import { ok, err } from "#response";
import { defineTool } from "#tool";

export function registerMyTools(server: McpServer) {
  defineTool(server, "my_tool", {
    title: "My tool",
    description: "What it does and why structured output helps.",
    inputSchema: {
      path: z.string().describe("Path to operate on"),
    },
    outputSchema: {
      result: z.string(),
    },
    annotations: { readOnlyHint: true },
  }, async ({ path }) => {
    const result = await exec("mytool", ["--json", path]);

    if (result.exitCode !== 0) {
      return err(result.stderr, { result: "" });
    }

    return ok({ result: result.stdout.trim() });
  });
}

See docs/guides/adding-tools.md for the full guide.

Prerequisites

The following CLI tools must be installed for their respective tool groups to work:

  • Always required: Node.js >= 20

  • Filesystem/search: ls, tree, find, du, rg (ripgrep)

  • Git: git

  • Kubernetes: kubectl

  • Terraform/OpenTofu: terraform or tofu

  • Helm: helm

  • ArgoCD: argocd

  • JSON: jq

  • YAML: yq (mikefarah/yq)

  • .NET: dotnet (.NET SDK)

  • Liquibase: liquibase

  • Python: ruff (lint), mypy (typecheck), pytest (test)

Tools gracefully return errors if their underlying CLI is not installed.

License

Apache-2.0

Available Tools

65 tools
argo_app_detailArgoCD app detailA
Read-only

Get detailed status for a single ArgoCD application including resource health.

Inputs: name (required). Returns: name, message, project, retained, +5 more

argo_app_diffArgoCD app diffB
Read-only

Show what's out of sync for an ArgoCD application.

Inputs: name (required). Returns: diff, hasDiff, retained

argo_app_health_summaryArgoCD app health summaryA
Read-only

Diagnose an ArgoCD application's health in one call: overall sync/health, likely causes, suggested next commands, and the unhealthy resources/conditions as evidence.

Inputs: name (required). Returns: name, status, healthy, evidence, +4 more

argo_appsArgoCD applicationsB
Read-only

List ArgoCD applications with sync/health status. Structured summary instead of table output.

Inputs: project, selector. Returns: apps, count, summary, retained

bash_lintBash lint (structured)A
Read-only

Run shellcheck and return structured diagnostics with file, line, column, message, and SC rule code. Much more compact than raw shellcheck output. Use minSeverity to filter by severity level.

Inputs: files, maxItems, detailLevel, minSeverity. Returns: total, errors, retained, truncated, +2 more

bash_syntax_checkBash syntax check (structured)A
Read-only

Check shell scripts for syntax errors with bash -n and return structured diagnostics (file, line, message). Parses without executing, so it is safe on untrusted scripts. Reports valid:true when no errors are found.

Inputs: files, maxItems, detailLevel. Returns: total, valid, errors, retained, +2 more

bash_testBash test (structured)A

Run a shell test script — bats .bats files via --tap, or a plain .sh harness — and return structured results: per-case pass/fail plus a summary parsed from TAP or N tests, M failures output, falling back to exit-code-only when the format is unrecognized. Executes the script, so it is gated by BASH_MCP_MODE.

Inputs: cwd, file, timeout. Returns: failed, passed, skipped, summary, +2 more

batchRun commands in parallelA

Run multiple commands in parallel and return all results. Each command is a binary plus an args array, executed without a shell (for a pipeline use command='sh', args=['-c', '...']). Use when you need to gather independent pieces of information in a single tool call instead of multiple sequential calls.

Inputs: commands. Returns: elapsed, results, retained

catRead file contentsA
Read-only

Read one or more files with line numbers and smart truncation. Returns structured output with metadata. Pass path for a single file, or paths to read several in one call (returns { files, count }) — collapsing what would otherwise be multiple round-trips. For large files, use startLine/endLine or maxLines to limit output. Use ref to read from a git branch/commit instead of disk (e.g. ref='main'). NOTE: reading with cat does NOT satisfy the built-in Edit/Write "must read first" guard (it tracks only the built-in Read tool) — run the built-in Read on a file immediately before editing it.

Inputs: ref, path, paths, endLine, +3 more. Returns: path, size, count, error, +7 more

check_environmentCheck environmentA
Read-only

Report which CLIs are installed (and their versions) so you can pick the right tool before calling it. Probes are client-only and non-blocking — no server/auth calls. Includes kubectl's current context when available.

Inputs: no named parameters. Returns: tools, total, retained, installedCount

dotnet_buildBuild (structured)A

Run dotnet build and return structured diagnostics with file, line, column, message, and error code. Much more compact than raw MSBuild output. Warnings are omitted by default; pass includeWarnings:true (or detailLevel:'full') to include them.

Inputs: cwd, project, maxItems, detailLevel, +2 more. Returns: total, summary, exitCode, retained, +4 more

dotnet_testTest (structured)A

Run dotnet test and return structured results: pass/fail/skip counts, failure messages. Much more compact than raw test output. Only failures are listed.

Inputs: cwd, filter, project. Returns: total, failed, passed, skipped, +4 more

duDisk usageA
Read-only

Show disk usage for paths. Returns entries as [path, sizeBytes] pairs, in the order du emits them. Use maxDepth to control how deep the summary goes.

Inputs: path (required), maxDepth. Returns: entries, retained

find_filesFind filesA
Read-only

Find files by name pattern, type, or modification time. Returns structured list of paths. Use names for multiple glob patterns (OR logic), modifiedWithin for recent files (e.g. '7d', '1h').

Inputs: name, path, type, names, +4 more. Returns: count, files, metadata, retained

gh_pr_checksPR checksA
Read-only

Report a pull request's CI checks as counts per state plus the failing and pending checks. Defaults to the current branch's PR; passing checks are counted, not listed, unless all=true.

Inputs: pr, all, cwd. Returns: checks, counts, retained

gh_run_failure_summaryCI run failure summaryA
Read-only

Diagnose a GitHub Actions run in one call: status, the failed jobs and steps, and the ##[error] lines from the failed log as evidence. Defaults to the latest run on the current branch.

Inputs: cwd, run, branch. Returns: run, url, branch, status, +6 more

git_branchesGit branchesB
Read-only

List git branches. Returns the current branch and [name, lastCommit] pairs; a remote branch's name starts with remotes/.

Inputs: cwd, remote. Returns: current, branches, retained

git_diffGit diffA
Read-only

Structured git diff: files changed with insertions/deletions counts. Use base+ref for two-ref comparison (e.g. base='main', ref='feature'). Use path to scope to one or more files or directories.

Inputs: cwd, ref, base, path, +1 more. Returns: files, retained, fileCount, totalDeletions, +1 more

git_diff_contentGit diff with contentA
Read-only

Show git diff with structured patch content. Returns parsed hunks per file instead of raw unified diff text. Use this when you need to see actual code changes, not just file-level stats. Use base+ref for two-ref comparison (e.g. base='main', ref='feature'). Use path to scope to one or more files or directories.

Inputs: cwd, ref, base, path, +2 more. Returns: files, summary, retained

git_logGit logA
Read-only

Structured git log: commit hash, author, date, message. Compact and parseable. Use range for ref comparisons (e.g. 'main..feature'). Use exclude to filter out commits matching a pattern (e.g. 'ci:').

Inputs: cwd, path, count, range, +4 more. Returns: count, commits, retained

git_pr_contextGit PR contextA
Read-only

Collect the commits and file changes of a branch vs a base ref (for writing a PR description): commit list, changed files with status, and a diffstat over base...head.

Inputs: cwd, base, head. Returns: base, head, files, changes, +2 more

git_statusGit statusA
Read-only

Structured git status: branch, staged/unstaged/untracked files. Replaces parsing raw git status output.

Inputs: cwd. Returns: ahead, clean, behind, branch, +4 more

glab_ci_statusGitLab pipeline statusA
Read-only

Report a GitLab pipeline's jobs as counts per status plus the failed, running and pending jobs. Defaults to the current branch's latest pipeline; pass mr for a merge request's head pipeline. Passing, skipped and manual jobs are counted, not listed, unless all=true.

Inputs: mr, all, cwd, repo, +2 more. Returns: url, jobs, counts, status, +2 more

glab_pipeline_failure_summaryGitLab pipeline failure summaryA
Read-only

Diagnose a GitLab pipeline in one call: status, the failed jobs and why GitLab says they failed, and the last script lines of each failed job's trace as evidence. Allowed-to-fail jobs are noted, not counted as the failure. Defaults to the current branch's latest pipeline.

Inputs: mr, cwd, repo, branch, +1 more. Returns: url, branch, status, evidence, +5 more

globGlob file searchB
Read-only

Find files matching a glob pattern. Returns a compact list of paths.

Inputs: pattern (required), cwd. Returns: count, files, retained

helm_listHelm releasesB
Read-only

List Helm releases with status, chart, and app version. Structured output.

Inputs: filter, context, namespace, allNamespaces. Returns: count, releases, retained

helm_release_triageHelm release triageA
Read-only

Diagnose a Helm release's health in one call: combines helm status + helm history into current status, likely causes, suggested next commands, and recent-revision evidence.

Inputs: release (required), context, namespace. Returns: status, healthy, evidence, retained, +4 more

helm_statusHelm release statusC
Read-only

Get detailed status of a Helm release.

Inputs: release (required), context, namespace. Returns: name, notes, status, retained, +4 more

helm_valuesHelm release valuesB
Read-only

Get the computed values for a Helm release as structured data.

Inputs: release (required), context, allValues, namespace. Returns: values, retained

jqjq JSON processorA
Read-only

Query and transform JSON using jq expressions. Accepts a file path or raw JSON string. Returns parsed, structured output — far more compact than reading a full JSON file. The filter is passed directly to jq (no shell), so shell-style escaping such as backslash-escaped quotes is neither needed nor supported — write the filter exactly as jq expects it.

Inputs: file, input, slurp, filter, +2 more. Returns: result, retained, multiline

kube_contextsKubectl contextsA
Read-only

List available kubectl contexts with current context marked.

Inputs: no named parameters. Returns: current, contexts, retained

kube_deployment_statusDeployment rollout statusB
Read-only

Report a deployment's rollout health (ready/desired replicas, conditions) as a structured diagnosis.

Inputs: name (required), context, namespace. Returns: status, evidence, retained, likelyCauses, +1 more

kube_diagnose_podDiagnose a podA
Read-only

Diagnose why a pod is unhealthy in one call. Returns status, likely causes, suggested next commands, and evidence (CrashLoopBackOff/ImagePullBackOff/OOMKilled/Unschedulable/restarts).

Inputs: pod (required), context, namespace. Returns: status, evidence, retained, likelyCauses, +1 more

kube_events_summarySummarize warning eventsA
Read-only

Summarize Warning events in a namespace (grouped by reason, ordered by count) instead of scrolling raw kubectl get events.

Inputs: context, maxItems, namespace, includeRaw, +2 more. Returns: total, status, evidence, retained, +3 more

kube_getKubectl get resourcesA
Read-only

Get Kubernetes resources as structured data. Wraps kubectl get -o json and returns a compact summary by default. Use the jq param to extract specific fields from the raw JSON (e.g. '.spec.template.spec.containers[].env') instead of the summary.

Inputs: jq, name, context, maxItems, +7 more.

kube_logsKubectl logsA
Read-only

Get pod logs. lines are as kubectl prints them, ' ', oldest first; consecutive repeats of a message merge into the first, marked ' [×N]', and a budget cut keeps the newest. Use grep to filter lines by regex pattern (e.g. 'ERROR|WARN') instead of piping through shell commands.

Inputs: pod, grep, tail, since, +7 more. Returns: lines, total, retained, truncated

kube_pod_failure_summarySummarize failing podsA
Read-only

List unhealthy pods in a namespace with their failure reason and evidence — one call instead of get + describe per pod.

Inputs: context, maxItems, namespace, includeRaw, +2 more. Returns: pods, total, status, evidence, +4 more

liquibase_statusPending changesets (structured)A
Read-only

List Liquibase changesets not yet applied to the target database, as structured JSON. Reports up-to-date vs a pending list. liquibase is on PATH — no mise/wrapper needed.

Inputs: cwd, labels, contexts, extraArgs, +2 more. Returns: pending, retained, upToDate, pendingCount

liquibase_update_sqlPreview migration SQL (structured)A
Read-only

Render the SQL Liquibase would run for pending changesets (updateSQL) as structured per-changeset summaries with a SQL-Server batch lint. Does NOT apply changes. SQL bodies are omitted unless includeRaw or changesetId is set. liquibase is on PATH — no mise/wrapper needed.

Inputs: cwd, labels, contexts, maxItems, +7 more. Returns: total, retained, truncated, changesets, +1 more

liquibase_validateValidate changelog (structured)A
Read-only

Validate a Liquibase changelog and return a structured pass/fail result with per-changeset errors (duplicate ids, checksum drift). Much more compact than raw output. liquibase is on PATH — no mise/wrapper needed.

Inputs: cwd, labels, contexts, extraArgs, +2 more. Returns: valid, errors, retained, errorCount

list_guidanceList tool-selection guidanceA
Read-only

Return an intent → preferred-tool index so you can pick the right bash-mcp tool for a goal. Each entry names the tool to prefer, raw-command anti-patterns to avoid, and why. Filter with intent (substring) or category to narrow the list.

Inputs: intent, category. Returns: total, intents, retained

lsList directoryA
Read-only

List files in a directory. Returns entries as [name, size, permissions, modified] — directories end with '/' and links with '@'. Use nameOnly for names alone, recursive for one level of subdirectories, all to include hidden files.

Inputs: all, path, nameOnly, recursive. Returns: entries, retained

npm_lintLint (structured)A

Run biome check and return structured diagnostics with file, line, column, message, and rule. Far more compact and parseable than raw lint output. Use minSeverity to filter by severity level.

Inputs: cwd, fix, paths, maxItems, +2 more. Returns: total, errors, retained, truncated, +3 more

npm_testTest (structured)A

Run vitest or jest (picked from package.json) and return structured test results: suites, pass/fail counts, failure messages. Much more compact than raw test output. Only failures are listed by default; use verbose=true for all tests.

Inputs: cwd, pattern, verbose, coverage. Returns: suites, summary, retained

npm_typecheckType check (structured)A
Read-only

Run tsc/tsgo --noEmit and return structured type errors with file, line, column, message, and TS error code. Much more compact than raw tsc output. Auto-detects tsgo for faster checking. Use project to specify a tsconfig.

Inputs: cwd, project, maxItems, detailLevel. Returns: total, errors, success, retained, +2 more

outlineFile structure outlineA
Read-only

Show the structural outline of a file — function/class names, top-level comments, imports. Returns a compact view without implementation bodies. Includes git metadata (branch, commit) when the file is in a git repo. Use instead of cat when reviewing file structure or auditing many files at once.

Inputs: path (required), ref. Returns: path, mtime, branch, commit, +6 more

python_lintPython lint (structured)B

Run ruff check and return structured diagnostics with file, line, column, message, and rule code. Much more compact than raw ruff output. Use minSeverity to filter by severity level.

Inputs: cwd (required), fix, paths, maxItems, +2 more. Returns: total, errors, retained, truncated, +3 more

python_testPython test (structured)A

Run pytest and return structured test results: suites, pass/fail counts, failure messages. Much more compact than raw test output. Only failures are listed by default; use verbose=true for all tests.

Inputs: cwd (required), path, pattern, verbose. Returns: suites, summary, retained

python_typecheckPython type check (structured)A
Read-only

Run mypy and return structured type errors with file, line, column, message, and error code. Much more compact than raw mypy output.

Inputs: cwd (required), paths, maxItems, detailLevel. Returns: total, errors, success, retained, +2 more

repo_health_summaryRepo health summaryA
Read-only

One-call snapshot of a git working tree: branch, ahead/behind vs upstream, staged/unstaged/untracked counts, recent commits, and the uncommitted diffstat.

Inputs: cwd, commits. Returns: ahead, clean, behind, branch, +6 more

result_getGet Retained ResultA
Read-only

Page through a result the response budget trimmed. Pass the retained.id from that response; path selects a field (dotted, e.g. files.0), offset/limit slice an array. Snapshot of the original call, kept for retained.expiresInSec.

Inputs: id, path, limit, offset. Returns: id, path, tool, total, +4 more

rgRipgrep searchA
Read-only

Search file contents with ripgrep. Returns files as [file, "line:text", ...] rows (a context line is "line-text"), [file, count] under countPerFile, [file] under filesOnly. Use glob (string or array, '!' to exclude) to filter files, ignoreCase for case-insensitive search, filesOnly for just filenames, countPerFile for match counts per file, maxPerFile to cap hits per file. For 'collect all X' tasks use only:true to return just the matched substrings (one row per hit) — add replace ($1 capture groups) to extract structured values.

Inputs: glob, only, path, context, +9 more. Returns: files, retained, truncated, matchCount, +1 more

runRun a commandA

Run a single command — a binary plus an args array, executed directly without a shell (so no pipes, redirects, or ';'/'&&' in the string) — and return structured output with smart truncation. Pass the binary as command and its arguments as args (e.g. command='npm', args=['test']); for a real shell pipeline run the shell yourself: command='sh', args=['-c', 'a | b > c']. Keeps the last N lines of output by default (where errors typically appear), or the first N with mode='head'. Use for build, test, and lint commands where you need exit code and error details, not full verbose output.

Inputs: command (required), cwd, args, mode, +4 more. Returns: stderr, stdout, elapsed, exitCode, +3 more

run_seqRun commands in sequenceA

Run an ordered list of labeled commands one after another, stopping at the first failure by default. Use for dependent steps (e.g. build then test then package) where order matters and a later step is pointless if an earlier one fails. Unlike batch (parallel), run_seq is sequential and short-circuits; set stopOnError=false to run every step regardless.

Inputs: steps, maxLines, stopOnError. Returns: steps, elapsed, exitCode, failedAt, +1 more

tf_backend_infoTerraform backend infoA
Read-only

Report the configured backend type and config for an initialized project. Reads .terraform/terraform.tfstate — run init first.

Inputs: cwd (required). Returns: type, config, retained

tf_modules_summaryTerraform modules summaryA
Read-only

List the modules used by an initialized Terraform/OpenTofu project (key, source, version). Reads .terraform/modules/modules.json — run init first.

Inputs: cwd (required). Returns: count, modules, retained

tf_outputsTerraform outputsA
Read-only

List Terraform/OpenTofu outputs as [name, value] pairs; a sensitive output is redacted to [name] alone.

Inputs: cwd (required), binary. Returns: outputs, retained

tf_plan_summaryTerraform plan summaryA
Read-only

Run terraform plan and return a structured summary of changes (add/change/destroy counts and affected resources). Each action is create, update, delete, replace or read; a replace counts in add and destroy, as terraform's Plan line does.

Inputs: cwd (required), binary, target, varFile, +1 more. Returns: add, change, changes, destroy, +2 more

tf_providersTerraform providersC
Read-only

List the Terraform/OpenTofu version and selected provider versions for the project.

Inputs: cwd (required), binary. Returns: version, retained, providers

tf_showTerraform showB
Read-only

Show current Terraform state as structured JSON. Returns resource summary with types and attributes.

Inputs: cwd (required), binary. Returns: count, retained, resources

tf_state_listTerraform state listA
Read-only

List resources in Terraform state. Returns the resource addresses, plus a byType rollup once there are more than 20 (type, name, and module are readable from each address).

Inputs: cwd (required), binary. Returns: byType, retained, resources

tf_validate_summaryTerraform validate summaryA
Read-only

Validate the Terraform/OpenTofu config and return a compact pass/fail summary with diagnostics.

Inputs: cwd (required), binary. Returns: valid, retained, errorCount, diagnostics, +1 more

tf_workspacesTerraform workspacesA
Read-only

List Terraform workspaces with current workspace marked.

Inputs: cwd (required), binary. Returns: current, retained, workspaces

treeDirectory treeA
Read-only

Show directory structure as a compact tree. Returns structured nodes instead of ASCII art. Use dirsOnly for directory-only view, pattern to filter by glob, maxDepth to control depth.

Inputs: path (required), exclude, pattern, dirsOnly, +1 more. Returns: dirs, files, paths, retained

yqyq YAML processorA
Read-only

Query and transform YAML files using yq expressions (mikefarah/yq). Outputs as JSON for structured consumption. Far more compact than reading a full YAML file.

Inputs: file, input, expression, outputFormat. Returns: format, result, retained

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 65 tools

    Disambiguation3/5

    Most tools target a distinct tool/resource (kube vs helm vs argo vs tf vs per-language lint/test), but several pairs are near-neighbors: find_files vs glob, git_diff vs git_diff_content, tf_state_list vs tf_show, and the cluster of '*_health_summary'/'*_failure_summary'/'*_diagnose' triage tools overlap conceptually with the plain getters they wrap. Descriptions do resolve most of these, but at 65 tools an agent must read carefully to avoid picking e.g. kube_get over kube_diagnose_pod when a diagnosis is wanted.

    Naming Consistency3/5

    Everything is snake_case, which is good, but the prefix/verb ordering is mixed: domain-prefixed noun-first (git_status, kube_get, tf_plan_summary, argo_app_diff) coexists with verb-first (list_guidance, check_environment, result_get) and bare Unix-style names (ls, tree, du, rg, glob, cat, jq, yq, run, batch). Readable, but not a single predictable pattern.

    Tool Count2/5

    65 tools is very heavy, even for a broad shell/devops toolbox spanning git, k8s, Terraform, ArgoCD, Helm, four language toolchains, and CI. Each tool is defensible in isolation, but the surface invites selection errors and could be consolidated (e.g. per-language lint/typecheck/test trios, summary vs getter variants).

    Completeness4/5

    Read/inspect coverage is deep across every advertised domain (files, git, Terraform, k8s, ArgoCD, Helm, CI, language toolchains), and run/batch act as an escape hatch for anything missing. Gaps are mostly write-side: no git mutations (commit/checkout/push), no kube apply/scale/exec, no file edit—though run largely works around them.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Provides MCP servers that wrap common developer tools such as git, npm, Docker, Kubernetes, and test runners, returning schema-validated structured JSON instead of raw terminal text. This lets AI agents consume typed, token-efficient results directly without brittle string parsing or platform-dependent formatting issues.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Wraps developer tools like git, npm, Docker, and test runners to return clean, schema-validated JSON instead of raw terminal text. This lets agents use typed, token-efficient results directly without brittle string parsing.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to work with developer tools such as git, npm, Docker, and test runners through structured, schema-validated JSON outputs. Reduces token usage and eliminates fragile terminal text parsing for reliable cross-platform workflows.
      4 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to invoke common developer tools such as git, npm, Docker, and test runners and receive clean, schema-validated JSON instead of fragile terminal text, reducing token usage and parsing errors.
      4 npm
      MIT