worktree-tools-mcp

Worktree Tools MCP Server

MCP server for automated git worktree management with Claude. Enables Claude to create, manage, and clean up git worktrees automatically.

Features

• Automatic username detection - From GitHub CLI or git config
• Full worktree management - Create, list, cleanup worktrees
• Dependency installation - Auto-detects and runs pnpm/npm/yarn
• .env file copying - Automatically copies environment files
• GitHub integration - Create PRs directly from worktrees
• Status checking - Check if worktrees are clean and ready for PR

Installation

Option 1: npm (Global)

npm install -g worktree-tools-mcp

Option 2: Install from GitHub

npm install -g git+https://github.com/georgeasoto/worktree-tools-mcp.git

Option 3: npx (No Installation)

Use directly with npx: ``bash npx -y git+https://github.com/georgeasoto/worktree-tools-mcp.git ``

Option 4: Local Development

git clone https://github.com/georgeasoto/worktree-tools-mcp.git
cd worktree-tools-mcp
npm install
npm run build
npm link

Configuration for Claude Code

Add to your Claude Code configuration file (typically ~/.config/Claude/claude_desktop_config.json or similar):

Option 1: Using npx (Recommended - Always up to date)

{
  "mcpServers": {
    "worktree-tools": {
      "command": "npx",
      "args": ["-y", "git+https://github.com/georgeasoto/worktree-tools-mcp.git"]
    }
  }
}

Option 2: If installed globally

{
  "mcpServers": {
    "worktree-tools": {
      "command": "worktree-tools-mcp"
    }
  }
}

Option 3: Local development

{
  "mcpServers": {
    "worktree-tools": {
      "command": "node",
      "args": ["/Users/YOUR_USERNAME/worktree-tools-mcp/dist/index.js"]
    }
  }
}

After adding the configuration, restart Claude Code to enable the MCP server.

Available Tools

create_worktree

Create a new git worktree with automatic setup.

Parameters:

• ticket (required): Ticket number (e.g., "CO-4493", "PROJ-123")
• branchName (required): Branch name (spaces converted to hyphens)
• cwd (optional): Working directory (defaults to current)
• openIde (optional): Open in IDE after creation ("cursor", "vscode", "auto")

Example: ``typescript { "ticket": "CO-4493", "branchName": "billing feature" } ``

What it does:

1. Auto-detects username from GitHub CLI or git config
2. Creates worktree at ../<repo-name>-worktrees/username/TICKET/branch-name
3. Creates branch: username/TICKET/branch-name
4. Fetches latest changes from origin/master
5. Auto-detects and installs dependencies (pnpm/npm/yarn)
6. Copies all .env files from main repo

list_worktrees

List all worktrees with status information.

Parameters:

• cwd (optional): Working directory

Returns:

• Array of worktrees with branch, path, and status
• Status includes: clean/dirty, commits ahead/behind

cleanup_worktree

Remove a worktree and optionally delete its branch.

Parameters:

• worktreePath (required): Path to worktree to remove
• deleteBranch (optional): Also delete the local branch (default: false)
• cwd (optional): Working directory

What it does:

1. Removes the worktree directory
2. Optionally deletes the local branch
3. Cleans up empty parent directories

worktree_status

Get the status of a worktree.

Parameters:

• worktreePath (required): Path to worktree to check

Returns:

• Clean/dirty status
• Commits ahead/behind master
• Ready for PR status
• Human-readable message

create_pr

Create a GitHub pull request from a worktree.

Parameters:

• worktreePath (required): Path to worktree
• title (optional): PR title (auto-generated from commits if not provided)
• body (optional): PR body (auto-generated if not provided)
• draft (optional): Create as draft PR (default: false)

Requirements:

• GitHub CLI must be authenticated (gh auth login)
• Or set GITHUB_TOKEN environment variable

Returns:

• PR URL
• PR number
• PR title

Usage Examples with Claude

Once configured, Claude can automatically manage worktrees:

Example 1: Create a new worktree `` User: "Create a worktree for ticket CO-1234 called payment integration" Claude: [calls create_worktree tool] Claude: "I've created a new worktree at ~/repos/myproject-worktrees/username/CO-1234/payment-integration with dependencies installed and .env files copied. The worktree is ready to use." ``

Example 2: List all worktrees ``` User: "Show me all my active worktrees" Claude: [calls list_worktrees tool] Claude: "You have 3 active worktrees:

1. CO-1234/payment-integration - 5 commits ahead, clean
2. CO-5678/user-dashboard - 2 commits ahead, uncommitted changes
3. CO-9012/api-refactor - up to date"

**Example 3: Create PR from worktree**

User: "Create a PR for my payment integration work" Claude: [calls create_pr tool] Claude: "I've created PR #123: 'Add payment integration' URL: https://github.com/org/repo/pull/123" ```

Example 4: Clean up worktree `` User: "Clean up the payment integration worktree" Claude: [calls cleanup_worktree tool with deleteBranch: true] Claude: "I've removed the worktree and deleted the local branch." ``

Username Detection

Usernames are automatically detected with this priority:

1. Manual override - From .worktree-config file in repo root
2. GitHub CLI - Uses gh api user --jq .login
3. Git config - Converts user.name to username format (lowercase, hyphens)

If detection fails, you'll get a clear error message with instructions.

Directory Structure

Worktrees are organized as: `` ~/repos/ ├── myproject/ (main repository) └── myproject-worktrees/ (all worktrees) └── username/ ├── CO-1234/ │ └── payment-integration/ └── CO-5678/ └── user-dashboard/ ``

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test the MCP server
npm run build && node dist/index.js

Companion Bash Scripts

This MCP server complements the worktree-tools bash scripts (located at ~/.checkout-scripts/ or ~/.worktree-tools/). You can use both:

• Bash scripts - For manual CLI usage
• MCP server - For Claude automation

Both implement the same logic and can be used interchangeably. The bash scripts provide a zero-dependency CLI interface, while the MCP server enables Claude to automate worktree operations.

Requirements

• Node.js 18+
• Git
• Optional: GitHub CLI (gh) for better username detection and PR creation
• Optional: pnpm, npm, or yarn for dependency installation

License

MIT