Gtr

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

Install

Via npx (no install)

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

Global install

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

From source

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

How it works

gtr-mcp operates on the git repository at the working directory it is launched in. Set your MCP client's cwd field to the repository root. One server instance = one repo context. Multi-repo: add a separate MCP server entry per repo in your client config, each with its own cwd.

This mirrors how gtr itself works — git gtr discovers its repo from the current directory via git rev-parse --git-common-dir, with no path argument required.

MCP client configuration

Claude Desktop / Claude Code

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

{
  "mcpServers": {
    "gtr": {
      "command": "npx",
      "args": ["gtr-mcp"],
      "cwd": "/path/to/your/repo"
    }
  }
}

Cursor

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

Multi-repo setup

{
  "mcpServers": {
    "gtr-frontend": {
      "command": "npx",
      "args": ["gtr-mcp"],
      "cwd": "/path/to/frontend"
    },
    "gtr-backend": {
      "command": "npx",
      "args": ["gtr-mcp"],
      "cwd": "/path/to/backend"
    }
  }
}

Configuration

Env var	CLI arg	Description
GTR_BIN	--gtr-bin <path>	Path to the gtr binary (default: git gtr via PATH). Binary locator only — not a repo selector.

The cwd field in your MCP client config is the only repo-selection mechanism.

Tools

Tool	Safety	Required params	Description
worktree_list	SAFE	—	List all worktrees with path, branch, status
worktree_status	SAFE	branch	Git status for a worktree (staged/unstaged/untracked, ahead/behind)
worktree_path	SAFE	branch	Resolve a branch/identifier to its absolute filesystem path
worktree_create	MODIFY	branch	Create a new worktree (and branch if needed)
worktree_copy	MODIFY	from	Copy files (by glob pattern) from one worktree into others; use dry_run: true to preview
worktree_rename	MODIFY	old_branch, new_branch	Rename a worktree and its branch atomically
worktree_remove	DESTRUCTIVE	branch, confirm: true	Remove a worktree from disk and git registry
worktree_clean	MODIFY/DESTRUCTIVE	—	Prune stale entries; confirm: true required with merged/closed

No tool accepts a repo_path argument. The server is cwd-bound.

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.

worktree_copy does not require a confirm gate: it is file-copy only (wraps gtr copy, which uses cp internally). It overwrites matching files in the target but cannot delete your pre-existing files — gtr's only directory-prune paths act on freshly-copied trees under the repo's own trusted .gtrconfig, never on existing target files. Use dry_run: true to preview before committing a real copy.

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.

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.

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 warning — not a git repo

gtr-mcp warning: "/some/path" is not a git repository. ...

The server started but the cwd is not a git repository. Set the MCP client's cwd field to the repository root (the directory containing .git).

Development

npm install
npm run build      # tsc compile
npm test           # vitest (parser + schema + integration if gtr available)
npm run typecheck  # 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, makeHandlers factory
  __tests__/
    parsers.test.ts      Parser unit tests (parsePorcelainList, parseGitStatus)
    schemas.test.ts      Schema validation tests (confirm gate, coercion, cwd model)
    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