# bash-mcp (npm · @nickw8/bash-mcp)

Structured JSON wrappers for git, kubectl, terraform, helm, argocd, gh, glab and other CLIs.

- Trust score: 74/100 (medium)
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-10-24

## Components

- npm · `@nickw8/bash-mcp`: 74/100 (this document), [markdown](https://verifymcp.io/servers/nickw8-bash-mcp/nickw8-bash-mcp.md), [page](https://verifymcp.io/servers/nickw8-bash-mcp/nickw8-bash-mcp)

## Channel facts

- Registry: `npm`
- Package: `@nickw8/bash-mcp`
- Version: `5.0.1`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-10-24.

- **Supply Chain Security**: 81/100
  - No malware found by supply-chain analysis.
  - CVE check failed: a known high-severity CVE affects zod 3.25.76, a direct dependency. A fixed version is available.
  - No install/post-install scripts declared.
  - 30 of 93 dependencies flagged as unhealthy.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to nickw8/bash-mcp).
  - Clear OSI-approved license (Apache-2.0).
  - Actively maintained (last published 0 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 69/100
  - AI-judged instruction clarity (good).
  - Context-footprint check failed: tool/resource definitions use about 8161 tokens (~125/item across 65 items; 65 tools + 0 resources), over budget; trim descriptions and params.
  - Usage-examples check failed: none of the tools include examples.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: not enough scan history yet (needs a 30-day window).
- **Tool Coverage**: 100/100
  - 100% of tools have a non-trivial description (not blank, and not just the tool's name).
  - 100% of tool parameters carry a description.
  - Structured output schemas are declared (98% of tools); any adoption earns full credit.
- **Tool Safety**: 100/100
  - No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.
  - We read all 65 captured tool definition(s), and no name or description among them implies an irreversible operation.
  - An AI judge read all 66 captured unit(s) of tool text and found none that tries to manipulate the model reading it.
- **Capabilities**: 100/100
  - Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.

**Unverified: 1 category.** A category scored 0 because we could not verify it: a data source with nothing on this package, evidence we could not reach, or a check we could not run. We only credit what we can confirm.

## Install

### How do I install the bash-mcp server?

bash-mcp runs locally as an npm package, launched with npx -y @nickw8/bash-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.

### Claude

```bash
claude mcp add nickw8-bash-mcp -- npx -y @nickw8/bash-mcp
```

### Cursor

```json
{
  "mcpServers": {
    "nickw8-bash-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@nickw8/bash-mcp"
      ]
    }
  }
}
```

### VS Code

```json
{
  "servers": {
    "nickw8-bash-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@nickw8/bash-mcp"
      ]
    }
  }
}
```

### Codex

```bash
codex mcp add nickw8-bash-mcp -- npx -y @nickw8/bash-mcp
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "nickw8-bash-mcp": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "@nickw8/bash-mcp"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add nickw8-bash-mcp --command npx --arg -y --arg @nickw8/bash-mcp
```

### Hermes

```yaml
mcp_servers:
  nickw8-bash-mcp:
    command: "npx"
    args: ["-y", "@nickw8/bash-mcp"]
```

### Netclaw

```json
{
  "McpServers": {
    "nickw8-bash-mcp": {
      "Transport": "stdio",
      "Command": "npx",
      "Arguments": [
        "-y",
        "@nickw8/bash-mcp"
      ]
    }
  }
}
```

### Vellum

```bash
assistant mcp add nickw8-bash-mcp -t stdio -c npx -a -y @nickw8/bash-mcp
```

### Other

```json
{
  "mcpServers": {
    "nickw8-bash-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@nickw8/bash-mcp"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-10-24 (score 74, +15)

- [security improvement] Malware scan: unverified → pass

### 2026-10-23 (score 59)

First indexed and scored.

## MCP tools (65)

### `ls` (~108 tokens)

List directory

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.

Input parameters:

- `all` (boolean): Include hidden files
- `nameOnly` (boolean): Entries are [name] alone
- `path` (string): Required. Directory path to list
- `recursive` (boolean): Recurse into subdirectories (1 level)

Output parameters:

- `entries` (array)
- `retained` (object)

### `tree` (~127 tokens)

Directory tree

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.

Input parameters:

- `dirsOnly` (boolean): Only show directories
- `exclude` (string): Pipe-separated patterns to exclude (default: node_modules|.git|dist|__pycache__|.venv|.next|.terraform)
- `maxDepth` (number): Max depth (default 3)
- `path` (string, required): Root directory
- `pattern` (string): Only show files matching glob pattern

Output parameters:

- `dirs` (number)
- `files` (number)
- `paths` (array)
- `retained` (object)

### `du` (~63 tokens)

Disk usage

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.

Input parameters:

- `maxDepth` (number): Depth to summarize
- `path` (string, required): Path to measure

Output parameters:

- `entries` (array)
- `retained` (object)

### `find_files` (~200 tokens)

Find files

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

Input parameters:

- `maxDepth` (number): Max search depth
- `modifiedWithin` (string): Modified within timespan (e.g. '7d', '1h')
- `name` (string): Filename glob pattern (e.g. '*.ts')
- `names` (array): Multiple filename glob patterns (e.g. ['*.ts', '*.py', '*.sh']). Combined with OR logic.
- `path` (string): Root directory to search (default: '.')
- `pattern` (string): Alias for name — filename glob pattern (e.g. '*.ts')
- `type` (string): Filter by type
- `withMetadata` (boolean): Include size (bytes) and mtime (unix timestamp) for each file

Output parameters:

- `count` (number)
- `files` (array)
- `metadata` (array)
- `retained` (object)

### `rg` (~451 tokens)

Ripgrep search

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.

Input parameters:

- `context` (number): Lines of context around each match
- `countPerFile` (boolean): Return match counts grouped by file instead of individual matches
- `filesOnly` (boolean): Only return filenames, not matched lines
- `fixedStrings` (boolean): Treat pattern as literal string
- `glob`: File glob filter(s); a string or array. Prefix with '!' to exclude (e.g. ['*.ts','!*.test.ts'])
- `ignoreCase` (boolean): Case-insensitive search
- `maxLineLength` (number): Window matched line text to ~this many chars centered on the match, so long/minified lines don't dump in full (0 = unlimited, default 120)
- `maxPerFile` (number): Cap matches per file (rg --max-count), independent of maxResults — keeps one hot file from dominating
- `maxResults` (number): Max results to return across all files (default 30). When the cap bites, the response reports the true totalMatches so you can decide whether to narrow the pattern or raise the cap
- `only` (boolean): Return only the matched substring(s), not the whole line — one row per match. Best for collecting tokens (versions, names, URLs)
- `path` (string): Directory or file to search (default: cwd)
- `pattern` (string): Required. Regex pattern to search for
- `replace` (string): Rewrite each match with this template ($1, $2 capture groups) and return the result; implies only-match extraction

Output parameters:

- `files` (array)
- `matchCount` (number): Matches returned; with countPerFile, the sum of counts
- `retained` (object)
- `totalMatches` (number)
- `truncated` (boolean): Present only when maxResults cut the matches

### `glob` (~50 tokens)

Glob file search

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

Input parameters:

- `cwd` (string): Working directory for the glob
- `pattern` (string, required): Glob pattern (e.g. 'src/**/*.ts')

Output parameters:

- `count` (number)
- `files` (array)
- `retained` (object)

### `git_status` (~39 tokens)

Git status

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

Input parameters:

- `cwd` (string): Repository path

Output parameters:

- `ahead` (number)
- `behind` (number)
- `branch` (string)
- `clean` (boolean)
- `retained` (object)
- `staged` (array)
- `unstaged` (array)
- `untracked` (array)

### `git_log` (~181 tokens)

Git log

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

Input parameters:

- `author` (string): Filter by author
- `count` (number): Number of commits (default 20)
- `cwd` (string): Repository path
- `exclude` (string): Exclude commits matching this grep pattern (uses --invert-grep)
- `path` (string): Filter by file path
- `range` (string): Git ref range (e.g. 'main..feature', 'HEAD~5..HEAD')
- `since` (string): Since date (e.g. '2024-01-01')
- `withFiles` (boolean): Include list of files changed per commit

Output parameters:

- `commits` (array)
- `count` (number)
- `retained` (object)

### `git_diff` (~143 tokens)

Git diff

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.

Input parameters:

- `base` (string): Base ref for two-ref comparison. When both ref and base are set, runs git diff <base> <ref>
- `cwd` (string): Repository path
- `path`: Limit diff to one or more files or directories (string or array)
- `ref` (string): Ref to diff against (e.g. 'main', 'HEAD~3')
- `staged` (boolean): Show staged changes

Output parameters:

- `fileCount` (number)
- `files` (array)
- `retained` (object)
- `totalDeletions` (number)
- `totalInsertions` (number)

### `git_branches` (~55 tokens)

Git branches

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

Input parameters:

- `cwd` (string): Repository path
- `remote` (boolean): Include remote branches

Output parameters:

- `branches` (array)
- `current` (string)
- `retained` (object)

### `repo_health_summary` (~71 tokens)

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.

Input parameters:

- `commits` (number): Number of recent commits to include (default 5)
- `cwd` (string): Repository path

Output parameters:

- `ahead` (number)
- `behind` (number)
- `branch` (string)
- `changes` (object)
- `clean` (boolean)
- `recentCommits` (array)
- `retained` (object)
- `staged` (number)
- `unstaged` (number)
- `untracked` (number)

### `git_pr_context` (~84 tokens)

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.

Input parameters:

- `base` (string): Base ref to compare against (default 'main')
- `cwd` (string): Repository path
- `head` (string): Head ref (default 'HEAD')

Output parameters:

- `base` (string)
- `changes` (object)
- `commits` (array)
- `files` (array)
- `head` (string)
- `retained` (object)

### `kube_get` (~282 tokens)

Kubectl get resources

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.

Input parameters:

- `allNamespaces` (boolean): Search all namespaces (overrides namespace)
- `context` (string): Kube context
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `includeLabels` (boolean): Include each resource's labels (default false — labels are verbose and mostly hashes; use selector to filter or jq to read specific ones)
- `includeRaw` (boolean): Include raw/verbose fields
- `jq` (string): jq filter applied to raw kubectl JSON. Skips the default summary and returns the jq result instead. Example: '.spec.template.spec.containers[].env'
- `maxItems` (integer): Item cap; overrides detailLevel
- `name` (string): Specific resource name
- `namespace` (string): Namespace (omit for all-namespaces or cluster-scoped)
- `resource` (string): Required. Resource type (e.g. pods, deployments, services, nodes)
- `selector` (string): Label selector (e.g. 'app=nginx')

### `kube_logs` (~252 tokens)

Kubectl logs

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.

Input parameters:

- `container` (string): Container name
- `context` (string): Kube context
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `grep` (string): Regex pattern to filter log lines (e.g. 'ERROR|WARN', 'timeout'). Only matching lines are returned.
- `ignoreCase` (boolean): Case-insensitive grep matching (default: false)
- `includeRaw` (boolean): Include raw/verbose fields
- `maxItems` (integer): Item cap; overrides detailLevel
- `namespace` (string): Namespace
- `pod` (string): Required. Pod name (or deployment/xxx)
- `since` (string): Duration like '1h', '30m'
- `tail` (number): Number of lines (default 100)

Output parameters:

- `lines` (array)
- `retained` (object)
- `total` (number)
- `truncated` (boolean)

### `kube_contexts` (~19 tokens)

Kubectl contexts

List available kubectl contexts with current context marked.

Output parameters:

- `contexts` (array)
- `current` (string)
- `retained` (object)

### `kube_diagnose_pod` (~81 tokens)

Diagnose a pod

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

Input parameters:

- `context` (string): Kube context
- `namespace` (string): Namespace
- `pod` (string, required): Pod name

Output parameters:

- `evidence` (array)
- `likelyCauses` (array)
- `retained` (object)
- `status` (string)
- `suggestedNextCommands` (array)

### `kube_pod_failure_summary` (~122 tokens)

Summarize failing pods

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

Input parameters:

- `allNamespaces` (boolean): Search all namespaces (overrides namespace)
- `context` (string): Kube context
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `includeRaw` (boolean): Include raw/verbose fields
- `maxItems` (integer): Item cap; overrides detailLevel
- `namespace` (string): Namespace

Output parameters:

- `evidence` (array)
- `likelyCauses` (array)
- `pods` (array)
- `retained` (object)
- `status` (string)
- `suggestedNextCommands` (array)
- `total` (number)
- `truncated` (boolean)

### `kube_deployment_status` (~56 tokens)

Deployment rollout status

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

Input parameters:

- `context` (string): Kube context
- `name` (string, required): Deployment name
- `namespace` (string): Namespace

Output parameters:

- `evidence` (array)
- `likelyCauses` (array)
- `retained` (object)
- `status` (string)
- `suggestedNextCommands` (array)

### `kube_events_summary` (~124 tokens)

Summarize warning events

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

Input parameters:

- `allNamespaces` (boolean): Search all namespaces (overrides namespace)
- `context` (string): Kube context
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `includeRaw` (boolean): Include raw/verbose fields
- `maxItems` (integer): Item cap; overrides detailLevel
- `namespace` (string): Namespace

Output parameters:

- `evidence` (array)
- `likelyCauses` (array)
- `retained` (object)
- `status` (string)
- `suggestedNextCommands` (array)
- `total` (number)
- `truncated` (boolean)

### `tf_state_list` (~74 tokens)

Terraform state list

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

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory

Output parameters:

- `byType` (object)
- `resources` (array)
- `retained` (object)

### `tf_show` (~52 tokens)

Terraform show

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

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory

Output parameters:

- `count` (number)
- `resources` (array)
- `retained` (object)

### `tf_plan_summary` (~142 tokens)

Terraform plan summary

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.

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory
- `planFile` (string): Path to a saved plan file (from `terraform plan -out`); summarized via `show -json` instead of re-running plan.
- `target` (string): Target specific resource
- `varFile` (string): Var file to use

Output parameters:

- `add` (number)
- `change` (number)
- `changes` (array)
- `destroy` (number)
- `noChanges` (boolean)
- `retained` (object)

### `tf_workspaces` (~46 tokens)

Terraform workspaces

List Terraform workspaces with current workspace marked.

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory

Output parameters:

- `current` (string)
- `retained` (object)
- `workspaces` (array)

### `tf_outputs` (~62 tokens)

Terraform outputs

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

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory

Output parameters:

- `outputs` (array)
- `retained` (object)

### `tf_providers` (~52 tokens)

Terraform providers

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

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory

Output parameters:

- `providers` (array)
- `retained` (object)
- `version` (string)

### `tf_validate_summary` (~55 tokens)

Terraform validate summary

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

Input parameters:

- `binary` (string): terraform or tofu (default $TF_BINARY, else terraform)
- `cwd` (string, required): Terraform project directory

Output parameters:

- `diagnostics` (array)
- `errorCount` (number)
- `retained` (object)
- `valid` (boolean)
- `warningCount` (number)

### `tf_modules_summary` (~49 tokens)

Terraform modules summary

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

Input parameters:

- `cwd` (string, required): Terraform project directory

Output parameters:

- `count` (number)
- `modules` (array)
- `retained` (object)

### `tf_backend_info` (~43 tokens)

Terraform backend info

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

Input parameters:

- `cwd` (string, required): Terraform project directory

Output parameters:

- `config` (object)
- `retained` (object)
- `type` (string)

### `argo_apps` (~49 tokens)

ArgoCD applications

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

Input parameters:

- `project` (string): Filter by ArgoCD project
- `selector` (string): Label selector

Output parameters:

- `apps` (array)
- `count` (number)
- `retained` (object)
- `summary` (object)

### `argo_app_detail` (~33 tokens)

ArgoCD app detail

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

Input parameters:

- `name` (string, required): Application name

Output parameters:

- `conditions` (array)
- `healthStatus` (string)
- `message` (string)
- `name` (string)
- `project` (string)
- `resources` (array)
- `retained` (object)
- `revision` (string)
- `syncStatus` (string)

### `argo_app_diff` (~31 tokens)

ArgoCD app diff

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

Input parameters:

- `name` (string, required): Application name

Output parameters:

- `diff` (string)
- `hasDiff` (boolean)
- `retained` (object)

### `argo_app_health_summary` (~52 tokens)

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

Input parameters:

- `name` (string, required): Application name

Output parameters:

- `evidence` (array)
- `healthy` (boolean)
- `likelyCauses` (array)
- `name` (string)
- `retained` (object)
- `status` (string)
- `suggestedNextCommands` (array)
- `syncStatus` (string)

### `helm_list` (~72 tokens)

Helm releases

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

Input parameters:

- `allNamespaces` (boolean): Search all namespaces (overrides namespace)
- `context` (string): Kube context
- `filter` (string): Filter by release name regex
- `namespace` (string): Namespace (omit for all)

Output parameters:

- `count` (number)
- `releases` (array)
- `retained` (object)

### `helm_status` (~43 tokens)

Helm release status

Get detailed status of a Helm release.

Input parameters:

- `context` (string): Kube context
- `namespace` (string): Namespace
- `release` (string, required): Release name

Output parameters:

- `description` (string)
- `lastDeployed` (string)
- `name` (string)
- `namespace` (string)
- `notes` (string)
- `retained` (object)
- `revision` (number)
- `status` (string)

### `helm_values` (~65 tokens)

Helm release values

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

Input parameters:

- `allValues` (boolean): Include chart defaults (not just user-supplied)
- `context` (string): Kube context
- `namespace` (string): Namespace
- `release` (string, required): Release name

Output parameters:

- `retained` (object)
- `values` (object)

### `helm_release_triage` (~70 tokens)

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.

Input parameters:

- `context` (string): Kube context
- `namespace` (string): Namespace
- `release` (string, required): Release name

Output parameters:

- `evidence` (array)
- `healthy` (boolean)
- `likelyCauses` (array)
- `retained` (object)
- `revision` (number)
- `revisions` (number)
- `status` (string)
- `suggestedNextCommands` (array)

### `jq` (~162 tokens)

jq JSON processor

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.

Input parameters:

- `compact` (boolean): Compact output (-c)
- `file` (string): Path to a JSON file
- `filter` (string): jq filter expression (default: '.')
- `input` (string): Raw JSON string to process (alternative to file)
- `rawOutput` (boolean): Output raw strings without JSON encoding (-r)
- `slurp` (boolean): Read entire input into array (-s)

Output parameters:

- `multiline` (boolean)
- `result`
- `retained` (object)

### `yq` (~103 tokens)

yq YAML processor

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.

Input parameters:

- `expression` (string): yq expression (default: '.')
- `file` (string): Path to a YAML file
- `input` (string): Raw YAML string to process (alternative to file)
- `outputFormat` (string): Output format (default: 'json' for structured output)

Output parameters:

- `format` (string)
- `result`
- `retained` (object)

### `cat` (~342 tokens)

Read file contents

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.

Input parameters:

- `endLine` (number): Stop reading at this line (inclusive)
- `lineNumbers` (boolean): Prepend line numbers to each line (useful when locating a line). Does not register the file as read for the built-in Edit — use the built-in Read right before editing.
- `maxLines` (number): Max lines to return per file (default 200, use 0 for unlimited)
- `path` (string): Path to a single file
- `paths`: Read multiple files in one call; a string or array. Returns { files, count }; a per-file failure is reported in that file's `error` and does not abort the others.
- `ref` (string): Git ref to read from (e.g. 'main', 'HEAD~1', a commit hash). When set, reads file content from git (git show ref:path) instead of disk.
- `startLine` (number): Start reading from this line (1-based)

Output parameters:

- `content` (string)
- `count` (number)
- `error` (string)
- `files` (array)
- `mtime` (number): File modification time (unix timestamp)
- `path` (string)
- `range` (array)
- `retained` (object)
- `size` (number)
- `totalLines` (number)
- `truncated` (boolean)

### `outline` (~120 tokens)

File structure outline

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.

Input parameters:

- `path` (string, required): Path to the file
- `ref` (string): Git ref to outline (e.g. 'main', 'HEAD~1', a commit hash). When set, reads file content from git (git show ref:path) instead of disk.

Output parameters:

- `branch` (string|null): Current git branch, or null if not in a git repo
- `commit` (string|null): Last commit hash that touched this file, or null if not in a git repo
- `language` (string)
- `mtime` (number): File modification time (unix timestamp). 0 if using ref.
- `outline` (string)
- `outlineLines` (number)
- `path` (string)
- `retained` (object)
- `symbols` (number)
- `totalLines` (number)

### `run` (~347 tokens)

Run a command

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.

Input parameters:

- `args` (array): Arguments passed directly to the binary (e.g. ['test']). With command='sh', use ['-c', '<shell script>'].
- `collapse` (boolean): Merge consecutive repeated lines (timestamps ignored) into the first, marked ' [×N]' (default true). false = output verbatim.
- `command` (string, required): The binary to execute — NOT a shell string (e.g. 'npm', 'git', 'sh'). For pipes/redirects, use command='sh' and put the script in args.
- `cwd` (string): Working directory
- `maxBytes` (number): Optional cap on stdout/stderr byte length (UTF-8).
- `maxLines` (number): Max stdout/stderr lines to keep. 0 = unlimited.
- `mode` (string): Keep the last N lines (tail, default) or the first N (head).
- `timeout` (number): Timeout in ms

Output parameters:

- `elapsed` (number): Wall-clock execution time in milliseconds
- `exitCode` (number)
- `retained` (object)
- `stderr` (string)
- `stdout` (string)
- `stdoutLines` (number)
- `truncated` (boolean)

### `run_seq` (~142 tokens)

Run commands in sequence

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.

Input parameters:

- `maxLines` (number): Max stdout/stderr lines to keep per step. 0 = unlimited.
- `steps` (array): Required. Ordered steps to run sequentially
- `stopOnError` (boolean): Stop at the first step with a non-zero exit code (default true).

Output parameters:

- `elapsed` (number): Total wall-clock time in milliseconds
- `exitCode` (number): 0 if every step succeeded, else the first failure's code
- `failedAt` (number|null): Index of the first failing step, or null if all passed
- `retained` (object)
- `steps` (array)

### `batch` (~77 tokens)

Run commands in parallel

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.

Input parameters:

- `commands` (array): Required.

Output parameters:

- `elapsed` (number)
- `results` (array)
- `retained` (object)

### `git_diff_content` (~196 tokens)

Git diff with content

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.

Input parameters:

- `base` (string): Base ref for two-ref comparison. When both ref and base are set, runs git diff <base> <ref>
- `context` (number): Number of context lines around changes (passed as -U<n>)
- `cwd` (string): Working directory (git repo)
- `path`: Limit diff to one or more files or directories (string or array)
- `ref` (string): Diff against this ref (e.g. 'HEAD~1', 'main', a commit hash)
- `staged` (boolean): Show staged changes (--cached)

Output parameters:

- `files` (array)
- `retained` (object)
- `summary` (object)

### `npm_lint` (~161 tokens)

Lint (structured)

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.

Input parameters:

- `cwd` (string): Required. Project root directory
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `fix` (boolean): Auto-fix safe issues (default: false)
- `maxItems` (integer): Item cap; overrides detailLevel
- `minSeverity` (string): Minimum severity to include (e.g. 'error' drops warnings and info)
- `paths`: Specific path(s) to lint; a string or array (default: '.')

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `fixedCount` (number)
- `retained` (object)
- `total` (number)
- `truncated` (boolean)
- `warningCount` (number)

### `npm_test` (~108 tokens)

Test (structured)

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.

Input parameters:

- `coverage` (boolean): Enable coverage reporting
- `cwd` (string): Required. Project root directory
- `pattern` (string): Filter tests by filename pattern
- `verbose` (boolean): Include all tests in output (default: only failures)

Output parameters:

- `retained` (object)
- `suites` (array)
- `summary` (object)

### `npm_typecheck` (~139 tokens)

Type check (structured)

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.

Input parameters:

- `cwd` (string): Required. Project root directory
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `maxItems` (integer): Item cap; overrides detailLevel
- `project` (string): Path to tsconfig.json (default: auto-detected by tsc)

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `retained` (object)
- `success` (boolean)
- `total` (number)
- `truncated` (boolean)

### `dotnet_build` (~180 tokens)

Build (structured)

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.

Input parameters:

- `configuration` (string): Build configuration (e.g. Debug, Release)
- `cwd` (string): Required. Project root directory
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `includeWarnings` (boolean): Include warnings in the response (default: errors only, even on a successful build)
- `maxItems` (integer): Item cap; overrides detailLevel
- `project` (string): Path to .csproj or .sln file (default: auto-detected in cwd)

Output parameters:

- `diagnostics` (array)
- `errorCount` (number)
- `exitCode` (number)
- `retained` (object)
- `summary` (string)
- `total` (number)
- `truncated` (boolean)
- `warningCount` (number)

### `dotnet_test` (~99 tokens)

Test (structured)

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

Input parameters:

- `cwd` (string): Required. Project root directory
- `filter` (string): Test filter expression (e.g. 'FullyQualifiedName~MyTest')
- `project` (string): Path to .csproj or .sln file (default: auto-detected in cwd)

Output parameters:

- `exitCode` (number)
- `failed` (number)
- `failures` (array)
- `passed` (number)
- `retained` (object)
- `skipped` (number)
- `summary` (string)
- `total` (number)

### `liquibase_validate` (~186 tokens)

Validate changelog (structured)

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.

Input parameters:

- `changelogFile` (string): Changelog path (--changelog-file); usually set in the defaults file instead.
- `contexts` (string): Context expression to filter changesets (--contexts).
- `cwd` (string): Directory to run liquibase in (where the defaults file / changelog live).
- `defaultsFile` (string): Path to the Liquibase defaults file (--defaults-file), e.g. db-dev.properties. Usually carries the JDBC URL, credentials, and changelog path.
- `extraArgs` (array): Additional raw arguments appended to the liquibase invocation.
- `labels` (string): Label expression to filter changesets (--labels).

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `retained` (object)
- `valid` (boolean)

### `liquibase_update_sql` (~314 tokens)

Preview migration SQL (structured)

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.

Input parameters:

- `batchLint` (boolean): Lint each changeset for the SQL-Server 'routine DDL must lead its GO-batch' rule (default true).
- `changelogFile` (string): Changelog path (--changelog-file); usually set in the defaults file instead.
- `changesetId` (string): Return only this changeset's full rendered SQL (matches the changeset id).
- `contexts` (string): Context expression to filter changesets (--contexts).
- `cwd` (string): Directory to run liquibase in (where the defaults file / changelog live).
- `defaultsFile` (string): Path to the Liquibase defaults file (--defaults-file), e.g. db-dev.properties. Usually carries the JDBC URL, credentials, and changelog path.
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `extraArgs` (array): Additional raw arguments appended to the liquibase invocation.
- `includeRaw` (boolean): Include raw/verbose fields
- `labels` (string): Label expression to filter changesets (--labels).
- `maxItems` (integer): Item cap; overrides detailLevel

Output parameters:

- `changesetCount` (number)
- `changesets` (array)
- `retained` (object)
- `total` (number)
- `truncated` (boolean)

### `liquibase_status` (~178 tokens)

Pending changesets (structured)

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.

Input parameters:

- `changelogFile` (string): Changelog path (--changelog-file); usually set in the defaults file instead.
- `contexts` (string): Context expression to filter changesets (--contexts).
- `cwd` (string): Directory to run liquibase in (where the defaults file / changelog live).
- `defaultsFile` (string): Path to the Liquibase defaults file (--defaults-file), e.g. db-dev.properties. Usually carries the JDBC URL, credentials, and changelog path.
- `extraArgs` (array): Additional raw arguments appended to the liquibase invocation.
- `labels` (string): Label expression to filter changesets (--labels).

Output parameters:

- `pending` (array)
- `pendingCount` (number)
- `retained` (object)
- `upToDate` (boolean)

### `python_lint` (~159 tokens)

Python lint (structured)

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.

Input parameters:

- `cwd` (string, required): Project root directory
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `fix` (boolean): Auto-fix safe issues (default: false)
- `maxItems` (integer): Item cap; overrides detailLevel
- `minSeverity` (string): Minimum severity to include (e.g. 'error' drops warnings and info)
- `paths`: Specific path(s) to lint; a string or array (default: '.')

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `fixedCount` (number)
- `retained` (object)
- `total` (number)
- `truncated` (boolean)
- `warningCount` (number)

### `python_test` (~103 tokens)

Python test (structured)

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.

Input parameters:

- `cwd` (string, required): Project root directory
- `path` (string): Specific test path or file to run
- `pattern` (string): Filter tests by expression (-k pattern)
- `verbose` (boolean): Include all tests in output (default: only failures)

Output parameters:

- `retained` (object)
- `suites` (array)
- `summary` (object)

### `python_typecheck` (~111 tokens)

Python type check (structured)

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

Input parameters:

- `cwd` (string, required): Project root directory
- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `maxItems` (integer): Item cap; overrides detailLevel
- `paths`: Specific path(s) to check; a string or array (default: '.')

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `retained` (object)
- `success` (boolean)
- `total` (number)
- `truncated` (boolean)

### `bash_syntax_check` (~116 tokens)

Bash syntax check (structured)

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.

Input parameters:

- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `files`: Required. Shell script path(s) to check; a string or array
- `maxItems` (integer): Item cap; overrides detailLevel

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `retained` (object)
- `total` (number)
- `truncated` (boolean)
- `valid` (boolean)

### `bash_lint` (~132 tokens)

Bash lint (structured)

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.

Input parameters:

- `detailLevel` (string): Item preset: summary 20, normal 100, full (default; also skips the response budget)
- `files`: Required. Shell script path(s) to lint; a string or array
- `maxItems` (integer): Item cap; overrides detailLevel
- `minSeverity` (string): Minimum severity to include (e.g. 'error' drops warnings and info)

Output parameters:

- `errorCount` (number)
- `errors` (array)
- `retained` (object)
- `total` (number)
- `truncated` (boolean)
- `warningCount` (number)

### `bash_test` (~124 tokens)

Bash test (structured)

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.

Input parameters:

- `cwd` (string): Working directory
- `file` (string): Required. Test script path (.bats or .sh)
- `timeout` (number): Timeout in ms

Output parameters:

- `exitCode` (number)
- `failed` (array)
- `passed` (array)
- `retained` (object)
- `skipped` (array)
- `summary`

### `check_environment` (~54 tokens)

Check environment

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.

Output parameters:

- `installedCount` (number)
- `retained` (object)
- `tools` (array)
- `total` (number)

### `list_guidance` (~105 tokens)

List tool-selection guidance

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.

Input parameters:

- `category` (string): Exact category filter, e.g. 'kubernetes', 'git', 'terraform'.
- `intent` (string): Case-insensitive substring filter on the intent text.

Output parameters:

- `intents` (array)
- `retained` (object)
- `total` (number)

### `gh_pr_checks` (~104 tokens)

PR checks

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.

Input parameters:

- `all` (boolean): List passing and skipped checks too (default: only the rest)
- `cwd` (string): Repository path (default: the server's working directory)
- `pr` (string): PR number, URL or branch (default: the current branch's PR)

Output parameters:

- `checks` (array)
- `counts` (object)
- `retained` (object)

### `gh_run_failure_summary` (~108 tokens)

CI 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. Defaults to the latest run on the current branch.

Input parameters:

- `branch` (string): Branch whose latest run to read (default: the current branch)
- `cwd` (string): Repository path (default: the server's working directory)
- `run` (string|number): Run ID (default: the latest run on `branch`)

Output parameters:

- `branch` (string)
- `evidence` (array)
- `failedJobs` (array)
- `likelyCauses` (array)
- `retained` (object)
- `run` (number)
- `status` (string)
- `suggestedNextCommands` (array)
- `url` (string)
- `workflow` (string)

### `glab_ci_status` (~174 tokens)

GitLab pipeline status

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.

Input parameters:

- `all` (boolean): List passing, skipped and manual jobs too
- `branch` (string): Branch whose latest pipeline to read (default: current branch)
- `cwd` (string): Repository path (default: the server's working directory)
- `mr` (string|number): Merge request IID: read its head pipeline instead
- `pipeline` (string|number): Pipeline ID (default: the latest pipeline on `branch`)
- `repo` (string): GROUP/REPO or URL (default: the repo at `cwd`)

Output parameters:

- `counts` (object)
- `jobs` (array)
- `pipeline` (number)
- `retained` (object)
- `status` (string)
- `url` (string)

### `glab_pipeline_failure_summary` (~164 tokens)

GitLab 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. Allowed-to-fail jobs are noted, not counted as the failure. Defaults to the current branch's latest pipeline.

Input parameters:

- `branch` (string): Branch whose latest pipeline to read (default: current branch)
- `cwd` (string): Repository path (default: the server's working directory)
- `mr` (string|number): Merge request IID: read its head pipeline instead
- `pipeline` (string|number): Pipeline ID (default: the latest pipeline on `branch`)
- `repo` (string): GROUP/REPO or URL (default: the repo at `cwd`)

Output parameters:

- `branch` (string)
- `evidence` (array)
- `failedJobs` (array)
- `likelyCauses` (array)
- `pipeline` (number)
- `retained` (object)
- `status` (string)
- `suggestedNextCommands` (array)
- `url` (string)

### `result_get` (~115 tokens)

Get Retained Result

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.

Input parameters:

- `id` (string): Required. retained.id from a trimmed response
- `limit` (integer): Default 100
- `offset` (integer): Default 0
- `path` (string): Dotted path into the payload; omit for the whole payload

Output parameters:

- `capturedAt` (string)
- `id` (string)
- `offset` (number)
- `path` (string)
- `retained` (object)
- `tool` (string)
- `total` (number)
- `value`

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/nickw8-bash-mcp/nickw8-bash-mcp#diagnostics

## Score history

- 2026-10-24: 74
- 2026-10-23: 59

## Common questions

### What is the bash-mcp server?

bash-mcp is listed in the public MCP registry as io.github.nickw8/bash-mcp. Structured JSON wrappers for git, kubectl, terraform, helm, argocd, gh, glab and other CLIs. This page covers its npm package (@nickw8/bash-mcp).

### Is the bash-mcp server safe to use?

bash-mcp scores 74 out of 100 on VerifyMCP. We recorded 1 known advisory against it as of 24 October 2026. It declares no install or post-install scripts. Its build provenance is signed and verified. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.

### What tools does the bash-mcp server expose?

bash-mcp exposes 65 tools: ls, tree, du, find_files, rg, and 60 more. Their descriptions and schemas cost roughly 7,921 tokens of context every time the server is loaded.

### Is the bash-mcp server still maintained?

bash-mcp is still listed as active in the MCP registry. We last reached this channel on 24 October 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.

### What licence is the bash-mcp server under?

bash-mcp declares the Apache-2.0 licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.

## Links

- npm package: https://www.npmjs.com/package/@nickw8/bash-mcp
- Socket report: https://socket.dev/npm/package/@nickw8/bash-mcp
- Repository: https://github.com/nickw8/bash-mcp
- Changelog RSS feed: https://verifymcp.io/servers/nickw8-bash-mcp/nickw8-bash-mcp.xml
- Changelog JSON feed: https://verifymcp.io/servers/nickw8-bash-mcp/nickw8-bash-mcp.json
- HTML version of this page: https://verifymcp.io/servers/nickw8-bash-mcp/nickw8-bash-mcp