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

npm

npm install -g @bnomei/wtp-mcp-rs

npx (no install)

npx -y @bnomei/wtp-mcp-rs@latest --repo-root /path/to/repo

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

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:

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.