wtp-mcp-rs

A Model Context Protocol (MCP) server for wtp (Worktree Plus), written in Rust. It lets AI assistants manage Git worktrees via the wtp CLI.

For:

• Rust users who want cargo install and a native CLI.
• npm users who want npm install -g with prebuilt platform binaries.
• Git users who want safe, scriptable worktree automation.

Works in any Git repo. The wtp binary is required and must be on PATH (or set via --wtp-path / config).

Highlights

• Safety defaults: Hooks and branch deletion are disabled by default and must be explicitly enabled.
• Rich resources: Query worktree lists, resolved paths, grouped views, and repo overview.

Installation

Cargo (crates.io)

cargo install wtp-mcp-rs

Homebrew

brew install bnomei/wtp-mcp/wtp-mcp-rs

GitHub Releases

Download a prebuilt archive from the GitHub Releases page, extract it, and place wtp-mcp-rs on your PATH.

From source

git clone https://github.com/bnomei/wtp-mcp.git
cd wtp-mcp
cargo build --release

Quick Start

1. Add this MCP configuration. Examples for common MCP clients (pick one):

# Claude Code
claude mcp add --transport stdio --scope project wtp -- wtp-mcp-rs

# Codex CLI
codex mcp add wtp -- wtp-mcp-rs

# OpenCode (interactive)
opencode mcp add

# Amp (workspace)
amp mcp add --workspace wtp -- wtp-mcp-rs

{
  "mcpServers": {
    "wtp": {
      "command": "wtp-mcp-rs"
    }
  }
}

2. Run the MCP client from your repo root (or pass --repo-root / --config if you want to pin a different path). For Codex CLI, MCP config is global; use codex --cd /path/to/repo if you want to set the working root without changing directories.
3. Ensure wtp is installed and on PATH (or set --wtp-path / config).
4. Optional: run init-config once to generate .wtp.yml, then edit defaults.base_dir and hooks before using add-worktree.

Usage

MCP Configuration

Add the Quick Start snippet to your MCP client configuration. Example below includes all supported args (remove the ones you don't need):

{
  "mcpServers": {
    "wtp": {
      "command": "wtp-mcp-rs",
      "args": [
        "--wtp-path",
        "/usr/local/bin/wtp",
        "--config",
        "/path/to/config.toml"
      ]
    }
  }
}

If your MCP client launches servers from the repository root (project/workspace scope), you can omit --repo-root because wtp-mcp-rs defaults to the current working directory.

CLI Options

Option	Description	Default
--repo-root <path>	Repository root directory	Current working directory
--wtp-path <path>	Override path to wtp binary	Auto-detect
--config <path>	Path to TOML configuration file	None

Worktree Configuration (.wtp.yml)

wtp controls worktree layout and hooks via .wtp.yml in the repo root.

• init-config runs wtp init to generate .wtp.yml. The default template usually sets defaults.base_dir to ../worktrees and includes example hooks.
• Edit the file to choose your worktree base directory (e.g., .worktrees for in-repo worktrees).
• Hooks are optional post-create/remove actions (copy files, symlink dirs, run setup commands). They are blocked by default in this server unless security.allow_hooks = true.
• If .wtp.yml is missing, add-worktree creates a minimal config with defaults.base_dir = .worktrees and no hooks.

Minimal example:

version: "1.0"
defaults:
  base_dir: .worktrees

Merging changes from worktrees

Typical flow:

• Each worktree is a branch checkout in its own directory.
• Commit in that worktree.
• Merge into your target branch from any worktree (usually the "main" one):
  • git merge feature/x
  • or open a PR and merge on GitHub.

Sample Configuration (config.toml)

# Repository root (optional, defaults to cwd)
repo_root = "/path/to/repo"

[wtp]
# Path to wtp binary (optional, auto-detected from PATH)
path = "/usr/local/bin/wtp"

[security]
# Allow execution of wtp hooks (default: false)
allow_hooks = false
# Allow branch deletion with worktree removal (default: false)
allow_branch_delete = false

Security defaults (why destructive actions are blocked)

By default, potentially destructive operations are disabled:

• Hook execution: Disabled by default. Hooks can execute arbitrary code.
• Branch deletion: Disabled by default. The --with-branch and --force-branch flags on remove-worktree require explicit enablement.

To enable these features, add to your configuration file:

[security]
allow_hooks = true
allow_branch_delete = true

Tools

• list-worktrees - List all worktrees in the repository
• add-worktree - Create a new worktree for an existing or new branch
• remove-worktree - Remove a worktree (optionally with its branch)
• merge-worktree - Return a git merge command for a worktree branch
• init-config - Initialize wtp configuration in the repository
• get-worktree-path - Get the absolute path to a worktree
• shell-hook - Get shell hook script (bash/zsh/fish)
• shell-init - Get shell initialization script (bash/zsh/fish)

Resources

The server exposes the following MCP resources:

URI	Description
wtp://worktrees	List of all worktrees (raw)
wtp://worktrees/resolved	List of worktrees with resolved absolute paths
wtp://worktree/{name}	Details for a specific worktree
wtp://overview	Repository overview with worktrees and security settings
wtp://worktrees/by-branch-prefix	Worktrees grouped by branch prefix (feature/, bugfix/, etc.)

Skill

skills/git-worktree-plus-with-mcp/SKILL.md: Use this skill when the user wants to manage Git worktrees through the wtp MCP server (list, create, remove, resolve paths, init .wtp.yml, or prepare merge commands), especially when safety defaults around hooks and branch deletion matter.

Development

Running Tests

Unit tests (no wtp required):

cargo test --lib

Integration tests (requires wtp installed; tests skip if missing):

cargo test --test integration

License

MIT License - see LICENSE for details.