bash-mcp

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.

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.

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.

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').

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.

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

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

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:').

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.

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

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

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.

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.

Get pod logs. lines are as kubectl prints them, '<timestamp> <message>', 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.

List available kubectl contexts with current context marked.

Takes no parameters.

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

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

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

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

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).

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

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.

List Terraform workspaces with current workspace marked.

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

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

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

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

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

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

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

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

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

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

Get detailed status of a Helm release.

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

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

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.

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

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.

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.

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.

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.

Takes no parameters.

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.

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.

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.

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.

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.

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.