MCP server providing session-guarded git worktree management for AI agent pipelines.

git-workflow-mcp is a Model Context Protocol (MCP) server that exposes git operations as tools. It introduces session-based ownership — each MCP session gets a unique ID, and destructive operations (worktree removal, branch deletion, merge) are only allowed on resources created by the same session.

The server exposes different tool subsets depending on --mode:

read-remote is a superset of read-only; full is a superset of read-remote. No push, clone, or remote-configuration tools are exposed — those remain CLI-only.

session_start → worktree_add → (work) → commit → merge → worktree_remove → branch_delete

When an MCP session ends unexpectedly (e.g. a crash or timeout), the worktree it created remains registered under the original session ID. A new session cannot run merge, worktree_remove, or branch_delete on that worktree because session ownership does not match.

Use session_release to remove the ownership entry and unblock the new session:

# New session
session_start(repo_root)
session_release(name: "<worktree-name>")   # drops orphan ownership entry
worktree_remove / merge / branch_delete    # now succeeds

session_release is idempotent — calling it for an already-released or non-existent name always succeeds.

cargo install --path .

Add to your MCP client configuration (e.g. Claude Code settings.json):

{
  "mcpServers": {
    "git-workflow": {
      "command": "git-workflow-mcp",
      "args": ["--stdio"]
    }
  }
}

The server writes structured logs to both stderr and a rolling file, useful for diagnosing disconnects or hangs after the fact.

• Logs: written to $GIT_WORKFLOW_LOG_DIR (default ~/.cache/git-workflow-mcp/) as mcp.YYYY-MM-DD.log (daily rotation).
• Panic backtrace: on any thread panic, the backtrace is appended to panic.log in the same directory.
• Log level: --log-level CLI arg > GIT_WORKFLOW_LOG_LEVEL env > RUST_LOG env > warn default. Accepts EnvFilter syntax (e.g. git_workflow_mcp=debug).
• Heartbeat: an alive pid=... sid=... elapsed_s=... info line every 30 seconds, so the last-alive timestamp is always within half a minute of a crash.
• Shutdown reason: on exit a single shutting down reason=<kind> line is emitted. Kinds: stdin_eof (transport closed normally), service_error (rmcp returned error), sigterm, sigpipe, ctrl_c.

Licensed under either of

• MIT License
• Apache License, Version 2.0

at your option.