Migration Guide

Already have MCP servers configured in Claude Code? mcpzip can import them in one command.

Overview

Prerequisites

• mcpzip binary installed and in your PATH
• Existing Claude Code config with MCP servers

Step 1: Preview the Migration

Always start with a dry run:

mcpzip migrate --dry-run

Example output:

Dry run: would migrate 5 server(s) from /Users/you/.claude.json

1. Write mcpzip config to /Users/you/.config/compressed-mcp-proxy/config.json:
   - slack (stdio)
   - github (stdio)
   - todoist (http)
   - gmail (http)
   - linear (stdio)

2. Update /Users/you/.claude.json:
   - Remove 5 individual server entries
   - Add single "mcpzip" entry pointing to /usr/local/bin/mcpzip

tip

Review this output carefully. Make sure all your servers are listed and the transport types look correct.

Step 2: Run the Migration

mcpzip migrate

This does two things:

2a. Creates mcpzip config

A new file is written at ~/.config/compressed-mcp-proxy/config.json containing all your upstream servers:

~/.config/compressed-mcp-proxy/config.json

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@anthropic/slack-mcp"],
      "env": {
        "SLACK_TOKEN": "xoxb-your-token"
      }
    },
    "github": {
      "command": "gh-mcp"
    },
    "todoist": {
      "type": "http",
      "url": "https://todoist.com/mcp"
    }
  }
}

2b. Updates Claude Code config

Your Claude Code config is updated to replace all individual servers with a single mcpzip entry:

~/.claude.json (after migration)

{
  "mcpServers": {
    "mcpzip": {
      "type": "stdio",
      "command": "/usr/local/bin/mcpzip",
      "args": ["serve"]
    }
  }
}

Step 3: Restart Claude Code

Restart Claude Code to pick up the new config. You should see 3 tools: search_tools, describe_tool, and execute_tool.

Step 4: Add Semantic Search (Optional)

For better tool discovery, add a Gemini API key to your mcpzip config:

~/.config/compressed-mcp-proxy/config.json

{
  "gemini_api_key": "AIza...",
  "mcpServers": { ... }
}

---

What Gets Migrated

Item	Migrated?	Notes
Server names	Yes	Preserved exactly
command + args	Yes	For stdio servers
env variables	Yes	Including secrets
type: "http" + url	Yes	HTTP/SSE servers
headers	Yes	Custom auth headers
Non-MCP settings	No	Only mcpServers is touched

Secrets in Config

Your environment variables (API keys, tokens) are copied to the mcpzip config file as-is. Set appropriate permissions:

chmod 600 ~/.config/compressed-mcp-proxy/config.json

What Does Not Get Migrated

• Gemini API key -- add this separately
• Search settings -- defaults are used (model: gemini-2.0-flash, limit: 5)
• Timeout settings -- defaults are used (idle: 5 min, call: 120s)
• Non-MCP Claude Code settings -- untouched

---

Migration Flow

---

Rollback

If you need to undo the migration:

1. Restore from backup

If you backed up your Claude Code config before migration:

cp ~/.claude.json.bak ~/.claude.json

2. Manual rollback

Re-add your servers to your Claude Code config and remove the mcpzip entry.

3. Clean up mcpzip files

rm ~/.config/compressed-mcp-proxy/config.json
rm -rf ~/.config/compressed-mcp-proxy/cache/
rm -rf ~/.config/compressed-mcp-proxy/auth/

Back Up First

Before running mcpzip migrate, consider backing up your Claude Code config:

cp ~/.claude.json ~/.claude.json.bak