mcpzip 0.1.0

MCP proxy that aggregates multiple servers behind search + execute meta-tools
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

---
sidebar_position: 3.5
title: CLI Reference
description: Complete reference for all mcpzip commands, flags, and options
---

# CLI Reference

mcpzip provides three commands: `serve`, `init`, and `migrate`.

## `mcpzip serve`

Start the proxy server. This is the main command -- it starts mcpzip as an MCP server over stdio, ready for Claude Code to connect.

```bash
mcpzip serve [OPTIONS]
```

### Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--config <PATH>` | `~/.config/compressed-mcp-proxy/config.json` | Path to config file |

### Examples

```bash
# Start with default config
mcpzip serve

# Start with a custom config file
mcpzip serve --config /path/to/my-config.json
```

### Behavior

1. Loads configuration from disk
2. Loads cached tool catalog (instant -- no network required)
3. Starts serving MCP over stdio immediately
4. Spawns a background task to refresh the catalog by connecting to all upstream servers
5. Handles `Ctrl+C` for graceful shutdown

:::info Instant Startup
mcpzip serves from its disk cache on startup, so it is available immediately. The background refresh connects to upstream servers concurrently and merges any new or changed tools into the catalog. If a server fails to connect, its cached tools are preserved.
:::

### Logging

mcpzip logs to stderr (stdout is reserved for MCP protocol). Control log verbosity with `RUST_LOG`:

```bash
# Normal output (default)
mcpzip serve

# Debug logging
RUST_LOG=mcpzip=debug mcpzip serve

# Trace logging (very verbose)
RUST_LOG=mcpzip=trace mcpzip serve
```

---

## `mcpzip init`

Interactive setup wizard. Guides you through creating a config file.

```bash
mcpzip init
```

This command has no flags. It will:

1. Ask for your Gemini API key (optional, for semantic search)
2. Walk you through adding MCP servers
3. Write the config to `~/.config/compressed-mcp-proxy/config.json`

:::tip
If you already have MCP servers configured in Claude Code, use `mcpzip migrate` instead -- it is faster and preserves your existing setup.
:::

---

## `mcpzip migrate`

Automatically migrate your Claude Code MCP configuration to mcpzip.

```bash
mcpzip migrate [OPTIONS]
```

### Flags

| Flag | Default | Description |
|------|---------|-------------|
| `--config <PATH>` | `~/.config/compressed-mcp-proxy/config.json` | Output config file path |
| `--claude-config <PATH>` | Auto-detected | Path to Claude Code config |
| `--dry-run` | `false` | Show what would happen without writing files |

### Claude Code Config Detection

If `--claude-config` is not specified, mcpzip searches these paths in order:

1. `~/.claude.json`
2. `~/.claude/config.json`

### Examples

```bash
# Preview what will happen
mcpzip migrate --dry-run

# Migrate with defaults
mcpzip migrate

# Custom paths
mcpzip migrate --claude-config ~/.claude.json --config ~/my-mcpzip.json
```

:::warning
`mcpzip migrate` modifies your Claude Code config file. Use `--dry-run` first to verify what will change. See the [Migration Guide](/docs/migration-guide) for a detailed walkthrough.
:::

---

## Environment Variables

| Variable | Description |
|----------|-------------|
| `GEMINI_API_KEY` | Gemini API key for semantic search (overrides config file value) |
| `RUST_LOG` | Log level control (e.g., `mcpzip=debug`) |

---

## Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Error (config invalid, server unreachable, etc.) |

---

## File Locations

| Path | Purpose |
|------|---------|
| `~/.config/compressed-mcp-proxy/config.json` | Main configuration |
| `~/.config/compressed-mcp-proxy/cache/tools.json` | Cached tool catalog |
| `~/.config/compressed-mcp-proxy/auth/` | Persisted OAuth tokens |
| `~/.claude.json` | Claude Code config (primary) |
| `~/.claude/config.json` | Claude Code config (fallback) |