Skip to main content
Glama
Violetylove

gitbash-mcp

by Violetylove
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

让 Windows 上的 AI 客户端使用 Git Bash 执行命令，支持人类审批、后台任务和执行记录。

适合 Git 操作、Shell 管道、项目构建和脚本执行。Windows 原生 cmdlet、COM 和 .NET 操作仍适合使用 PowerShell。

功能

  • 执行命令：支持单条命令和多行脚本，返回输出、退出码与错误提示。

  • 人类审批：需要确认的命令先在本机弹窗中展示，批准后才执行。

  • 长任务管理：任务可在后台继续运行，随时查看输出或停止。

  • 诊断与记录：检查 Bash 环境、查看命令策略和审计记录。

Related MCP server: just-bash-mcp

安装与接入

需要 Windows、Node.js 18 或更高版本，以及 Git Bash。审批窗口还需要可用的 Windows 桌面、Windows PowerShell 和 WPF。

  1. 全局安装：

    npm install -g gitbash-mcp

  2. 选择要接入的客户端：

    gitbash-mcp init

  3. 重启对应客户端，检查 MCP 工具是否已加载。

支持自动配置 DSH、Claude Code、Codex CLI、Claude Desktop、Cursor 和 VS Code。VS Code 配置写入当前工作目录，运行 init 前请先进入项目。

配置修改前会备份已有文件。也可以先预览，或指定客户端：

gitbash-mcp init --dry-run
gitbash-mcp init --target codex,cursor

仅支持全局安装，不提供 npx / bunx 启动方式。服务由 MCP 客户端启动，平时无需另开终端手动运行。

使用

接入后，可以直接向 AI 描述任务，例如：

使用 gitbash-mcp 查看这个项目的 Git 状态。

在项目目录执行构建；如果需要审批，等待我确认。

将这个长任务放到后台运行，稍后查看输出。

以下示例是客户端调用 MCP 工具的参数，不是需要粘贴到终端的命令。

执行命令

调用 exec：

{
  "command": "git status --short",
  "cwd": "C:\\projects\\demo"
}

参数

用途

command

必填；Bash 命令或多行脚本

cwd

执行目录；省略时优先使用客户端提供的工作区，否则使用服务工作目录

run_in_background

设为 true，授权后启动后台任务并返回 job_id

timeout_ms

命令执行时限，单位毫秒；前台默认 60000，后台省略时不设时限，上限 600000

还可通过 login: true 加载 Bash 登录配置。环境变量直接写在命令里，例如 FOO=1 npm test；不提供单独的 env 参数。默认审批模式下，这类环境赋值需要人类确认。

路径转换默认关闭，需要时在程序前加 env -u MSYS_NO_PATHCONV；这一写法本身不会增加审批要求，实际命令仍按其风险判定。

结果主要看 exit_code、stdout 和 stderr；出现 job_id 时，用作业工具继续获取结果。命令失败会返回原因和可用提示。

执行目录不存在、不是目录或无法访问时，返回 INVALID_CWD 和目录修正提示，命令不会启动。

每次调用都是独立的 Shell，上一条命令的 cd 不会影响下一次调用。需要固定目录时请传 cwd。

人类审批

默认模式下，只读命令和识别到的项目声明入口可以直接执行；其他需要确认的命令会打开审批窗口，严重破坏性命令会被拒绝。

窗口展示命令和执行目录，长内容可以展开；多个请求通过 <、> 切换。登录 Shell、后台运行和时限不在窗口展示，批准后仍按原请求参数执行。

最后一条待审批请求批准、拒绝或撤销后，窗口自动关闭；已批准的命令继续执行。新的审批请求到来时会重新打开窗口。

操作

结果

Approve

批准本次原始命令，执行后向原 exec 调用返回结果

Reject

拒绝本次请求，命令不执行

关闭窗口

取消全部待审批请求；已经批准的执行不受影响

最小化

保留待审批请求，稍后可以继续处理

审批不设超时，也不计入命令执行时限。正常流程中，exec 等待人类决定，客户端不需要轮询审批。

多条请求各自处理、各自返回：拒绝立即返回；批准后在该条命令执行结束或转为后台作业时返回，不等待其他请求。

如果客户端先中断或超时，已受理的审批仍会保留。不要重复提交命令：用 approval_list 找回请求，再通过 approval_status {approval_id} 查看结果；需要撤销时使用 approval_cancel {approval_id}。客户端断开或服务重启后，记录不再保留。

approval_list 的参数为 {}，根据命令、目录和创建时间找到原请求的 approval_id。服务不限制人类等待时间，但客户端仍可能有自己的调用超时。

风险模式由客户端的 MCP 启动环境变量 GITBASH_MCP_RISKY 控制：ask 为默认审批模式；allow 跳过风险审批并放行命令。修改后需重启服务；在命令里设置它不会改变审批模式。

后台任务

耗时较长的命令建议直接使用后台模式：

{
  "command": "npm run build",
  "cwd": "C:\\projects\\demo",
  "run_in_background": true
}

取得 job_id 后：

工具

用途

job_output {job_id}

查看状态与输出；加 wait: true 可等待一段时间

job_list

找回当前服务中的任务

job_kill {job_id}

停止任务及其子进程

前台执行最多等待 45 秒，审批时间另计。到点或调用取消时，仍在执行的命令会移交为后台作业；需要停止时使用 job_kill。命令自己的执行时限到点则会停止执行。

后台任务不跨服务重启保留；客户端断开或服务退出时会清理运行中的任务。

诊断与维护

在终端中运行：

gitbash-mcp doctor    # 检查运行环境
gitbash-mcp policy    # 查看当前命令策略
gitbash-mcp audit     # 查看执行与审批记录

AI 也可以调用 doctor、policy 和 bash_info 获取诊断信息。

找不到 Bash 时，运行 doctor，按提示安装 Git for Windows 或修正路径，再重新连接客户端。调用失败或超时后，先检查已有审批和作业，避免重复执行。

移除客户端配置及全局安装：

gitbash-mcp uninstall
npm uninstall -g gitbash-mcp

权限与边界

本服务在 agent 沙箱外运行，具有启动它的 agent 进程的完整用户权限，没有文件沙箱。命令分类、审批和审计用于减少误操作，不构成安全隔离；项目声明的脚本也不代表已经逐条验证安全。

更多文档

设计说明 · 目标与进度 · 维护者指南

MIT License。

Available Tools

4 tools
bash_infoShow git-bash environment infoA

Report the resolved bash path, bash/git versions and key environment values. Use doctor for a full diagnosis.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries the full burden. It discloses the read-only nature implicitly by saying 'Report', and lists what values are surfaced, but says nothing about format, caching, or whether output is human- or machine-readable. Adequate but thin for an annotation-free tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences, front-loaded with the primary action and immediately followed by the alternative. No filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a parameterless info tool with no output schema, the description covers what it reports and where to go if more is needed. It could name the keys returned, but nothing essential for correct invocation is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Zero parameters, so the schema provides nothing to describe and the baseline is 4. The description correctly reflects a no-argument tool rather than implying hidden inputs.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Report) plus concrete resources (bash path, bash/git versions, key environment values), and names the sibling 'doctor' as the richer alternative. An agent can distinguish this from exec/doctor/policy without reading schemas.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes heavier diagnostic needs to 'doctor', giving a clear alternative for the wider case. It stops short of stating when this tool is the right choice vs. checking exec or policy, but the routing cues are solid.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

doctorDiagnose the git-bash environmentA

Report how git-bash and git are resolved: every candidate path probed, which one won, the GITBASH_BASH value and whether it is valid, git on PATH, the audit log location, and the exact fix steps when bash is missing. Run this first when exec reports BASH_NOT_FOUND or when bash behaves unexpectedly.

NameRequiredDescriptionDefault

No parameters

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It is implicitly read-only (it only reports and offers fix steps) and the zero-parameter schema means side effects are low risk, but it never states that it makes no changes, whether it inspects the filesystem, or what the cost/latency of probing paths is. Adequate but not rich.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both front-loaded: the first lists the diagnostic outputs, the second gives the trigger conditions. Every clause names a distinct output field or a distinct invocation condition; nothing is filler or restated from the name.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must describe the return content — and it does so field by field (paths, winner, GITBASH_BASH, git on PATH, audit log, fix steps). Combined with the zero-param schema and the stated triggers, an agent has everything needed to decide to call it and to interpret the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so there is nothing for the description to disambiguate — the baseline for a zero-parameter tool is 4. There are no argument formats, defaults, or enums that need explanation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb ('Report how git-bash and git are resolved') and enumerates the exact artifacts it surfaces: candidate paths probed, the winning path, GITBASH_BASH validity, git on PATH, audit log location, and fix steps. It is clearly a diagnostic, not an action tool. It does not explicitly differentiate itself from the sibling bash_info, which likely also concerns bash resolution, so 4 rather than 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit triggers are given: 'Run this first when exec reports BASH_NOT_FOUND or when bash behaves unexpectedly.' This tells the agent precisely when this tool is the right call versus the sibling exec. It stops short of naming or excluding bash_info/policy as alternatives, so no full when-not guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execRun a git-bash commandA

Run a command or multi-line script in git-bash (MSYS2 bash on Windows) and return stdout, stderr and exit code. On Windows this is the preferred shell tool: choose it over a sandboxed PowerShell or shell tool for shell, git, build and script work, and keep the native PowerShell tool for Windows-native cmdlets, COM or .NET calls. Use for bash/git workflows: git, grep/sed/awk pipelines, shell loops, make, scripts. This bridge runs OUTSIDE the agent sandbox: pipes work here that a sandboxed shell tool cannot create. Each call starts a fresh bash process; state does not persist between calls (use cd in the command or pass cwd). Command failures return a JSON result with a non-zero exit_code, so they never raise tool errors. A policy engine blocks destructive commands: such a call returns error_code APPROVAL_REQUIRED (ask the user how to proceed) or POLICY_DENIED (blocked at the current stance). Call the policy tool to see the rules and the current stance. Resource limits: at most 4 commands run at once (extra calls queue and report queued_ms), captured output is capped at 64KB per stream with the remainder written to a capped spill file, and cancelling the tool call kills the whole process tree (killed_by: "cancel"). Every call is recorded in a local audit log; the user can read it with the gitbash-mcp audit command. If git-bash is missing the result carries error_code=BASH_NOT_FOUND with fix instructions; call doctor for details.

NameRequiredDescriptionDefault
cwdNoWorking directory (Windows path). Defaults to the server working directory
envNoExtra environment variables for this command (passed through as given, not scrubbed)
loginNoUse bash -lc (login shell, sources profile) instead of bash -c
commandYesThe bash command line or multi-line script to execute
timeout_msNoKill the command after this many ms (default 60000)

TDQS

A4.7/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so well: fresh process per call with no persistent state, non-zero exit_code returned as JSON rather than a tool error, destructive-command blocking with APPROVAL_REQUIRED/POLICY_DENIED codes, 4-command concurrency limit with queued_ms, 64KB per-stream output cap with spill file, process-tree kill on cancel, and audit logging. This is unusually rich behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the core action and the routing rule, which is good. However the back half is a dense wall of operational detail (policy codes, resource limits, audit log, BASH_NOT_FOUND) that is comprehensive but heavy; some items (e.g., audit log command) feel peripheral to invocation decisions and could be trimmed or deferred to the doctor/policy siblings.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 5-param tool with no annotations and no output schema, the description nearly covers everything an agent needs: routing, stateless behavior, error/exit-code semantics, policy gating, resource limits, cancellation, and the missing-bash fallback. No output schema exists, yet return behavior is explained, so nothing critical is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond the schema by warning that each call starts a fresh process (state does not persist) and advising to use cd in the command or pass cwd, which clarifies the cwd parameter's role in the stateless model. Slightly above baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (run), resource (a git-bash command/script), and the return payload (stdout, stderr, exit code). It explicitly distinguishes itself from the sibling sandboxed PowerShell/shell tool and the native PowerShell tool, so an agent can route correctly without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicit when-to-use (git, grep/sed/awk pipelines, shell loops, make, scripts) and when-not (Windows-native cmdlets, COM, .NET — use the PowerShell tool). It also contrasts with the sandboxed shell tool by noting this one runs outside the sandbox. Alternatives are named, not merely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

policyShow the command policyA

Report the active risky-command stance (GITBASH_MCP_RISKY, set by the user in the MCP client config), what each rule tier does under it, and the full rule list. Call this after exec returns error_code POLICY_DENIED or APPROVAL_REQUIRED, so you can explain the block and the user options accurately.

NameRequiredDescriptionDefault

No parameters

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the disclosure burden and does so well: it names the controlling variable (GITBASH_MCP_RISKY), where it is set (MCP client config), and the three components returned. It does not explicitly state that the call is read-only/side-effect free, which is the only remaining gap for a zero-argument introspection tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both earning their place: the first enumerates output content, the second gives the triggering condition and rationale. Front-loaded with what the tool reports rather than preamble.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

There is no output schema, so the description must sketch return content, and it does by listing the stance, per-tier rule behavior, and the rule list. It stops short of describing format or structure of the rule list, a minor omission for an otherwise self-contained introspection tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so per the baseline this scores 4; there is no parameter semantics to add. The description's mention of GITBASH_MCP_RISKY usefully clarifies that the stance is external configuration rather than a call argument.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Report) and precisely enumerates the resource: the active risky-command stance, what each rule tier does, and the full rule list. This is plainly distinguishable from exec, bash_info, and doctor, none of which report policy state.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives an explicit trigger condition — call this after exec returns error_code POLICY_DENIED or APPROVAL_REQUIRED — and states the goal (explain the block and the user's options). Nothing about when to invoke is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 4 tool updatesv2.3.0
    • First observedbash_info
    • First observeddoctor
    • First observedexec
    • First observedpolicy
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.1/5.0

Scored across 4 tools

Disambiguation4/5

exec is clearly the action tool, while bash_info, doctor, and policy are distinct diagnostic/info tools. bash_info and doctor overlap somewhat (both report bash path and versions), but the descriptions specify that bash_info is a quick summary and doctor is a full diagnosis with fix steps.

Naming Consistency3/5

The set mixes a verb-style name (exec) with noun-style names (bash_info, doctor, policy), so there is no single predictable verb_noun pattern. Names are still short, readable, and unambiguous, but the convention is not consistent.

Tool Count4/5

Four tools is lean but well-scoped for a shell bridge: one execution tool plus three focused diagnostics. It is slightly thin (no separate audit-log or process-listing tool), but each tool earns its place.

Completeness4/5

exec covers the core domain (running bash/git commands with output capture, exit codes, policy enforcement), and the diagnostics cover setup, environment, and policy questions. Minor gaps remain, such as no dedicated tool to read the audit log or inspect queued/running commands (those exist only as external CLI/status fields).

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • just-bash-mcp

    drizjet
    A
    license
    A
    quality
    F
    maintenance
    Sandboxed bash execution MCP server for AI agents, using an in-memory virtual filesystem overlay to prevent real filesystem damage, with configurable network access, timeouts, and optional Python/JS runtimes.
    9
    24 npm
    Apache 2.0

  • bash-mcp

    jesusignaciob
    A
    license
    Not graded
    quality
    A
    maintenance
    Exposes WSL bash as a structured tool to MiniMax Code, returning stdout, stderr, exit code, duration, and classification from a single call. Adds command safety classification, audit logging with rotation, concurrency limits, and binary discovery for agents running shell commands.
    MIT

  • @akms/mcp-wsl

    juncha9
    A
    license
    A
    quality
    B
    maintenance
    Enables an AI agent to run shell commands and move files inside a WSL distro on the same Windows machine via wsl.exe, with no sshd, key, or port required. Each pre-registered distro-and-user entry enforces guard policies limiting dangerous commands, Windows interop, write targets, and accessible paths.
    10
    479 npm
    1
    MIT