hop-mcp

An MCP server for managing parallel Git worktrees. Work on multiple tickets simultaneously without stashing, switching branches, or losing context.

The Problem

You're deep in JIRA-456 when a critical bug comes in. Traditional workflow:

git stash
git checkout main
git checkout -b hotfix-789
# fix the bug
git checkout feature/JIRA-456
git stash pop   # hope nothing conflicts

With hop:

hop start HOTFIX-789
# fix the bug in isolated directory
hop to JIRA-456
# back to your original work, exactly as you left it

Each ticket gets its own directory. No stashing. No branch switching. No context loss.

Tools

Tool	Description
hop_list	List all worktrees with path, branch, commit, and dirty status
hop_start	Create a new worktree for a ticket (supports dryRun to preview)
hop_to	Switch to an existing worktree
hop_current	Get current worktree context (branch, ticket, dirty status)
hop_open	Open a worktree in Cursor IDE
hop_end	Remove a worktree (checks for uncommitted changes, supports dryRun)
hop_clean	Delete scratch files in a worktree

All tools also available as git_worktree_* aliases.

How It Works

Git worktrees create separate working directories that share the same .git object store:

my-project/                    # main worktree (your original clone)
my-project/.worktrees/
├── JIRA-123/                  # worktree for ticket JIRA-123
├── JIRA-456/                  # worktree for ticket JIRA-456
└── HOTFIX-789/                # worktree for hotfix

Benefits:

• Low disk usage — only working files are duplicated, git objects are shared
• Instant switching — just cd to another directory
• Full isolation — each worktree has its own node_modules, build cache, etc.
• No conflicts — uncommitted changes stay exactly where they are

Requirements

• Git 2.5+ (for worktree support)
• Node.js 20+

Install

npm install
npm run build

Setup

Claude Code

Add to ~/.claude.json under projects.<your-project>.mcpServers:

{
  "hop": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/hop-mcp/dist/index.js"]
  }
}

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "hop": {
      "command": "node",
      "args": ["/path/to/hop-mcp/dist/index.js"]
    }
  }
}

Configuration

Config is merged from (highest precedence first):

1. Per-repo: .hop-mcp.json at repository root
2. Global: ~/.config/hop-mcp/config.json (macOS/Linux) or %APPDATA%\hop-mcp\config.json (Windows)
3. Built-in defaults

Example .hop-mcp.json:

{
  "worktreesDir": ".worktrees",
  "defaultBaseBranch": "develop",
  "defaultBranchTemplate": "feature/<ticket>-<slug>",
  "defaultBranchTemplateNoSlug": "feature/<ticket>",
  "scratchGlobs": [".cursor/plans/**", "**/*.plan.md"]
}

Usage Examples

# See all active worktrees
hop list

# Start work on a new ticket
hop start JIRA-123

# Start with a descriptive slug
hop start JIRA-123 --slug fix-auth-timeout

# Preview what would be created (dry run)
hop start JIRA-123 --dry-run

# Switch to an existing ticket
hop to JIRA-123

# Check where you are
hop current

# Open ticket in Cursor
hop open JIRA-123

# Preview removal (shows dirty status)
hop end JIRA-123 --dry-run

# Remove when done (fails if uncommitted changes)
hop end JIRA-123

# Force remove with uncommitted changes
hop end JIRA-123 --force

License

MIT