claude-handoff-manager 0.1.0

MCP server that automates Claude Code conversation handoffs — no more manual copy-paste when you hit the message cap.

claude-handoff-manager

MCP server that automates Claude Code conversation handoffs. No more manual copy-paste when you hit the message cap.

The Problem

When a Claude Code conversation reaches the message limit, it produces a handoff summary. You then have to:

1. Copy the handoff text
2. Exit / clear the conversation
3. Start a new session
4. Paste the handoff as the first message

This is tedious and breaks your flow.

The Solution

This MCP server automates the entire handoff cycle:

1. End of conversation: Claude calls save_handoff - the message is saved to disk and copied to your clipboard
2. New conversation: Say "continue from last handoff" - Claude calls load_handoff and picks up exactly where you left off

Zero manual copy-paste.

Installation

Option A: uvx from Git (recommended for teams)

Push this repo to your team's Git host, then each developer adds it to their ~/.mcp.json:

{
  "mcpServers": {
    "handoff-manager": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/YOUR_ORG/claude-handoff-manager", "claude-handoff-manager"],
      "type": "stdio"
    }
  }
}

Option B: uvx from PyPI

{
  "mcpServers": {
    "handoff-manager": {
      "command": "uvx",
      "args": ["claude-handoff-manager"],
      "type": "stdio"
    }
  }
}

Option C: Run directly (local development)

{
  "mcpServers": {
    "handoff-manager": {
      "command": "python3",
      "args": ["/path/to/handoff-manager/src/handoff_manager/server.py"],
      "type": "stdio"
    }
  }
}

After editing ~/.mcp.json, restart Claude Code to pick up the new server.

Tools

Tool	What it does
save_handoff	Saves handoff message to ~/.claude/handoffs/ + copies to clipboard
load_handoff	Loads the latest (or a specific) handoff in a new conversation
copy_handoff_to_clipboard	Copies a saved handoff to the system clipboard
list_handoffs	Lists all saved handoffs with previews
delete_handoff	Deletes a specific or all handoffs

Usage

Saving (end of a conversation)

Claude will automatically call save_handoff when it generates a handoff summary at the message cap. You can also manually trigger it:

"Save a handoff with the current context"

Loading (start of a new conversation)

"Continue from last handoff"

or

"Load handoff"

Claude calls load_handoff and gets the full context from your previous session.

Listing saved handoffs

"Show me my saved handoffs"

Clipboard

"Copy the last handoff to my clipboard"

Storage

Handoffs are stored as JSON files in ~/.claude/handoffs/:

~/.claude/handoffs/
  20260611_143022_home-user-myproject.json
  20260611_100515_home-user-otherproject.json

Each file contains:

• id: Unique identifier (timestamp + project slug)
• created_at: UTC timestamp
• working_dir: The project directory
• project_name: Human-friendly name
• message: The full handoff text

Clipboard Support

Automatically copies to clipboard on save using:

• macOS: pbcopy
• Linux X11: xclip or xsel
• Linux Wayland: wl-copy
• Windows: clip

Requirements

• Python >= 3.10
• mcp SDK >= 1.0.0
• Claude Code CLI

License

MIT