gtr-mcp

An MCP (Model Context Protocol) server that wraps git-worktree-runner (gtr) so AI agents can manage git worktrees through a structured, safe tool interface.

Built as a contribution to issue #67.

Prerequisites

• Node.js 18+

• git gtr installed and on PATH (see gtr install docs) — or set GTR_BIN

• The repos you want to manage must have git initialized

Related MCP server: Code MCP Server

Install

Via npx (no install)

npx gtr-mcp --repo-path /path/to/your/repo

Global install

npm install -g gtr-mcp
gtr-mcp --repo-path /path/to/your/repo

From source

git clone https://github.com/coderabbitai/gtr-mcp
cd gtr-mcp
npm install
npm run build
node dist/index.js --repo-path /path/to/your/repo

MCP client configuration

Claude Desktop / Claude Code

Add to ~/.claude/claude_desktop_config.json or your project .mcp.json:

{
  "mcpServers": {
    "gtr": {
      "command": "node",
      "args": ["/path/to/gtr-mcp/dist/index.js"],
      "env": {
        "GTR_MCP_REPO_PATH": "/path/to/your/repo"
      }
    }
  }
}

Cursor

{
  "mcp": {
    "servers": {
      "gtr": {
        "command": "npx",
        "args": ["gtr-mcp"],
        "env": {
          "GTR_MCP_REPO_PATH": "/path/to/your/repo"
        }
      }
    }
  }
}

Configuration

Tools

Safety model

• SAFE — read-only. Can run freely.

• MODIFY — creates or rearranges state. Reversible with normal git operations.

• DESTRUCTIVE — removes state from disk and/or git registry. Requires confirm: true explicitly.

Confirm gate

worktree_remove always requires confirm: true. worktree_clean with merged: true or closed: true (without dry_run: true) also requires confirm: true. This is Zod-schema enforced — the gate cannot be bypassed by an agent that infers the wrong intent.

Security notes

No shell execution

All subprocess calls use execFile with argument arrays — never shell: true, never string interpolation into a shell command. User-controlled values (branch names, paths) are passed as argv elements, not shell tokens.

Trust boundary

gtr's .gtrconfig postCreate hooks only execute if a human previously ran git gtr trust in the repository. An agent cannot enable trust — the server exposes no trust tool. If worktree_create returns hooks_ran: false, a remediation message is included telling the human what to run.

Path restriction

Set GTR_MCP_REPO_BASE to prevent an agent from operating on arbitrary paths:

GTR_MCP_REPO_BASE=/Users/me/Developer gtr-mcp

Any repo_path outside the base is rejected before the gtr subprocess is invoked.

Porcelain output (Gate-0 finding)

gtr list --porcelain outputs tab-separated path\tbranch\tstatus with raw unescaped values — list.sh calls _tsv_unescape_field when reading stored records and then prints raw via printf. No un-escape pass is needed on our side. A branch or path containing a literal tab character would corrupt the TSV output — this is a known gtr limitation, not a bug in this server.

The exec tool opt-in

worktree_exec is disabled by default. Even when enabled, prefer your shell tool:

cd "$(git gtr go branch-name)" && your-command

worktree_exec adds an indirection layer with no safety benefit over your native shell. Set GTR_MCP_ENABLE_EXEC=1 only if your client cannot run shell commands directly.

Prompts

The server exposes a gtr-workflow prompt with a markdown guide covering:

• When to use worktrees

• The standard create → work → status → remove loop

• Safety contract and trust model

• Path resolution behaviour

Fetch it via prompts/get with name: "gtr-workflow".

Troubleshooting

gtr not found

gtr-mcp startup failed: gtr not found (tried "git gtr")

Install gtr: https://github.com/coderabbitai/git-worktree-runner#installation

Or point at the binary directly:

GTR_BIN=/path/to/gtr gtr-mcp

Hooks skipped

If worktree_create returns "hooks_ran": false, the repository is not trusted. Have a human run git gtr trust in the repo root.

worktree_clean --merged fails (gh/glab not found)

The merged and closed flags require the GitHub CLI (gh) or GitLab CLI (glab) to be installed and authenticated. Install them and run gh auth login first.

Startup validation — not a git repo

Each tool call validates repo_path via git rev-parse --git-dir before invoking gtr. If you see Not a git repository, ensure the path points to a repo root (contains .git).

Development

npm install
npm run build      # tsc compile
npm test           # vitest (parser + schema + integration if gtr available)
npm run lint       # tsc --noEmit type check
npm run check      # FF-1: grep for shell execution patterns

Roadmap

• PR2: gtr --json mode would remove regex parsing fragility for worktree_create output (tracking worktree_path and hook state).

• Go binary distribution: a single static binary via go-mcpserver for simpler install.

File structure

src/
  index.ts               MCP server entry point, transport, dispatcher, prompts
  gtr.ts                 gtr subprocess wrapper, parsers, validators
  ff-check.ts            FF-1 fitness function (CI helper)
  tools/
    worktree.ts          Tool definitions, schemas, handlers, dispatch table
  __tests__/
    parsers.test.ts      Parser unit tests (parsePorcelainList, parseGitStatus)
    schemas.test.ts      Schema validation tests (confirm gate, coercion)
    integration.test.ts  Live gtr integration tests (skipped if gtr not on PATH)
.github/
  workflows/
    ci.yml               CI: build + FF-1 + FF-3 + test + lint
AGENTS.md                AI agent usage guide