Skip to main content
Glama
Sign In
hop-mcp

hop-mcp

by maciej-w
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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.

Related MCP server: Treehouse Worktree

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

Available Tools

14 tools
git_worktree_cleanB

Clean scratch files in a specific hop (git worktree) only. Deletes build artifacts, caches, or temp files without affecting other worktrees. Safer than global clean.

Inputs: slug, globs, branch, ticket, +3 more.

git_worktree_createA

Start a new hop (git worktree) for a ticket or feature. Creates an isolated directory for parallel development without switching branches. Pass a ticket ID like "JIRA-123" to auto-name the branch. IMPORTANT: After creating, tell the user they can use "hop to " to switch to it, or "hop open " to open it in Cursor. Then ask which they prefer.

Inputs: ticket (required), from, slug, branch, +2 more.

git_worktree_currentA

Get the current hop (git worktree) context. Returns the worktree info for the current working directory, including branch, path, dirty status, and parsed ticket/slug. Use this to understand "where am I?" and to enable resumability after context switches or retries.

Inputs: repoPath.

git_worktree_listA

List all hops (git worktrees) in a repository. Use this instead of "git worktree list". Shows each worktree path, branch, commit, and dirty status. IMPORTANT: After showing results, always display the hints from the response to help the user know their options (hop to, hop open, hop start).

Inputs: repoPath.

git_worktree_openA

Open a hop (git worktree) in Cursor IDE. Launches a new Cursor window at the worktree path. Use this when user wants to edit files in Cursor for a specific ticket/worktree.

Inputs: slug, branch, ticket, repoPath, +1 more.

git_worktree_removeA

End a hop (remove git worktree). Safely removes the worktree directory. Refuses if there are uncommitted changes unless force=true. Use when done with a ticket.

Inputs: slug, force, prune, branch, +5 more.

git_worktree_switchA

Hop to an existing git worktree by ticket ID, branch name, or path. Use this to switch context to a different ticket. Returns the worktree path. IMPORTANT: After calling this tool, you MUST immediately run the cd command from suggestedCommands to change the working directory.

Inputs: slug, branch, ticket, repoPath, +1 more.

hop_cleanB

Clean scratch files in a specific hop (git worktree) only. Deletes build artifacts, caches, or temp files without affecting other worktrees. Safer than global clean.

Inputs: slug, globs, branch, ticket, +3 more.

hop_currentA

Get the current hop (git worktree) context. Returns the worktree info for the current working directory, including branch, path, dirty status, and parsed ticket/slug. Use this to understand "where am I?" and to enable resumability after context switches or retries.

Inputs: repoPath.

hop_endA

End a hop (remove git worktree). Safely removes the worktree directory. Refuses if there are uncommitted changes unless force=true. Use when done with a ticket.

Inputs: slug, force, prune, branch, +5 more.

hop_listA

List all hops (git worktrees) in a repository. Use this instead of "git worktree list". Shows each worktree path, branch, commit, and dirty status. IMPORTANT: After showing results, always display the hints from the response to help the user know their options (hop to, hop open, hop start).

Inputs: repoPath.

hop_openA

Open a hop (git worktree) in Cursor IDE. Launches a new Cursor window at the worktree path. Use this when user wants to edit files in Cursor for a specific ticket/worktree.

Inputs: slug, branch, ticket, repoPath, +1 more.

hop_startA

Start a new hop (git worktree) for a ticket or feature. Creates an isolated directory for parallel development without switching branches. Pass a ticket ID like "JIRA-123" to auto-name the branch. IMPORTANT: After creating, tell the user they can use "hop to " to switch to it, or "hop open " to open it in Cursor. Then ask which they prefer.

Inputs: ticket (required), from, slug, branch, +2 more.

hop_toA

Hop to an existing git worktree by ticket ID, branch name, or path. Use this to switch context to a different ticket. Returns the worktree path. IMPORTANT: After calling this tool, you MUST immediately run the cd command from suggestedCommands to change the working directory.

Inputs: slug, branch, ticket, repoPath, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    B3.4/5.0

    Scored across 14 tools

    Disambiguation2/5

    Every tool exists twice as an exact alias pair (hop_list/git_worktree_list, hop_start/git_worktree_create, hop_to/git_worktree_switch, etc.) with identical descriptions, so an agent cannot tell which to pick. Within a single prefix the purposes are distinct, but the deliberate duplication makes half the surface indistinguishable.

    Naming Consistency2/5

    Two parallel naming schemes coexist for the same operations: a terse hop_* set and a git_worktree_* set, with mismatched verbs for the same action (hop_start vs git_worktree_create, hop_to vs git_worktree_switch, hop_end vs git_worktree_remove). Each scheme is internally readable, but mixing them for identical functionality breaks predictability.

    Tool Count3/5

    The reported 14 tools collapse to only 7 unique operations, so half the count is redundant aliasing rather than earned surface. The underlying 7-tool scope (list, current, start, to, end, clean, open) is reasonable for a git worktree helper.

    Completeness4/5

    The set covers the core worktree lifecycle: enumerate, inspect current context, create, switch, remove, clean, and open in an IDE. Only secondary git worktree operations (prune, lock/unlock, move, repair) are absent, which agents can work around via raw git.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers