contextzip MCP server

contextzip

Send your codebase to any AI chat. Get the changes back.

One command zips the right files for Claude or ChatGPT. Another writes the AI's reply into your project, without losing your own edits.

Try it in your browser  ·  Docs  ·  CLI reference  ·  Changelog

pip install contextzip      # or: npm i -g @contextzip/cli  ·  brew install akadeepesh/tap/contextzip
cz                          # zip the right files and put the ZIP on your clipboard
cz apply                # write the AI's reply back into your project

---

Why

Every AI coding session in a web chat starts the same way: hunt down the relevant files, leave out node_modules by hand, zip, upload. Then the slow part: copy the AI's edits back file by file, into the right folders, and hope you didn't overwrite something you changed in the meantime.

contextzip does both directions.

Knows your stack	62 languages and frameworks, from Next.js, Django and Spring Boot to .NET, Laravel, Flutter and C++. Each brings its own rules for what to leave out, and monorepos get all that apply.
Leaves out the noise	Dependencies, build output, caches, lockfiles, binaries and everything in your .gitignore. On this project's website repo that is 37,887 of 37,949 files.
Never sends secrets	.env, private keys, cloud credentials and Terraform state stay out. Include a .env on purpose and its keys are kept while every value becomes [REDACTED].
Pastes as a file	The ZIP goes on your clipboard as a real file, folders intact. Ctrl+V in Claude, ChatGPT or Gemini attaches it.
Brings the changes back	cz apply finds where each returned file belongs and three-way merges it against a snapshot of what you sent. Conflicts and cut-off files wait for your decision.
Stays on your machine	No telemetry. Packaging and applying make no network requests.

How it compares

Other tools turn a repository into one text file for an AI to read. contextzip sends the real files, and its main job is the way back.

	contextzip	repomix	gitingest	code2prompt
Output	ZIP of the real files	One text file (XML, Markdown, JSON)	One text digest	One templated prompt
Applies the AI's changes back	Yes, three-way merge	No	No	No
Reply to a repo as a pull request	Yes	No	No	No
What it leaves out	Rules for 62 stacks, plus .gitignore	One default list, plus .gitignore	.gitignore and your patterns	.gitignore and your globs
Secrets	Excluded, or redacted if included	Suspicious files are skipped	Not covered in its docs	Not covered in its docs
Remote repos without cloning	GitHub, GitLab, Bitbucket	GitHub	GitHub	Not covered in its docs
Runs in	Terminal, browser, VS Code, MCP	Terminal, browser, MCP	Terminal, browser	Terminal, MCP

If you only want an AI to read a repository, any of them works, and a single text file pastes into more places than a ZIP does. repomix can also compress code down to its signatures, which contextzip doesn't do yet. If you want the AI's edits back in your code, that is what contextzip is for.

The other columns come from each project's own documentation as of October 2026. Corrections are welcome.

Installation

pip install contextzip                    # Python 3.9+   (also: pipx install, uv tool install)
npm install -g @contextzip/cli            # no Python needed, any OS
brew install akadeepesh/tap/contextzip    # macOS, Linux

Every method installs two commands that do the same thing: contextzip and the shorter cz. To update later, run contextzip update.

Tab completion: cz completions --install sets it up for your shell (bash, zsh, fish or PowerShell), for both names. Open a new terminal and cz ap<Tab> completes to cz apply. cz doctor checks the install if something doesn't work.

# Windows (Scoop)
scoop bucket add contextzip https://github.com/akadeepesh/scoop-bucket
scoop install contextzip

# Try it once, nothing stays installed
npx @contextzip/cli
uvx contextzip
pipx run contextzip

• Direct download: grab an archive from the latest release, unpack it, and put the contextzip folder on your PATH. Builds exist for Windows x64, macOS (Apple Silicon and Intel) and Linux x64/arm64 (glibc 2.35 or newer).
• VS Code: install contextzip from the Marketplace, or run code --install-extension contextzip.contextzip. It bundles the CLI.
• AI agents: pip install "contextzip[mcp]" and register contextzip mcp as an MCP server (Python 3.10+).
• No install: contextzipcli.com.

pip installed contextzip, but put the cz command in a folder your terminal doesn't search. This is common with Python from the Microsoft Store on Windows, and with pip install --user on macOS and Linux. Python itself always works, so let contextzip fix PATH for you:

python -m contextzip setup-path     # macOS / Linux: python3 -m contextzip setup-path

On Windows this adds the folder to your user PATH (no admin needed). On macOS and Linux it adds one line to your shell's startup file. Open a new terminal and cz works. Until then, python -m contextzip does everything cz does. If you installed with pipx, run pipx ensurepath; with uv, uv tool update-shell.

Quick start

cd ~/projects/my-app
cz

No flags needed. contextzip detects your framework, leaves out the noise, writes codebase.zip and copies it to your clipboard:

contextzip · my-app   Next.js + FastAPI (backend/)

  44 files   186 KB → 63 KB zip   46,210 tokens

  src/app/           18,200  ████████████░░░░░░░░  39%
  src/components/    12,100  ████████░░░░░░░░░░░░  26%
  backend/api/        9,800  ██████░░░░░░░░░░░░░░  21%
  3 more folders      6,110  ████░░░░░░░░░░░░░░░░  14%

  Fits      Claude ≈23%  ·  ChatGPT 36%  ·  Gemini ≈5%
  Left out  36,176 files: node_modules/ (35,120), .next/ (904), 3 secret files

✓ On your clipboard. Paste it into Claude or ChatGPT.   snapshot #14
  When the AI replies, run: cz apply

Piped or in CI, and with --plain, the same run prints one plain line per step instead. Paste the ZIP into your AI tool, ask for what you want, and when it sends files back:

cz apply

The commands you'll use most:

cz --dry-run --verbose              # preview every included and excluded file, write nothing
cz --git-changes                    # only what you've changed
cz pick                             # choose files in a tree, then Enter packages them
cz include src/ app/                # only these folders
cz exclude tests/ '*.snap'          # everything except these
cz include src/ .env                # .env too, with its values redacted
cz --prompt "fix the login redirect bug"    # let AI pick the relevant files
cz github.com/user/repo             # a GitHub, GitLab or Bitbucket repo, without cloning it
cz --here                           # only the folder you're in (monorepos)
cz stacks                           # the languages and frameworks it recognises

Applying AI changes back

cz apply              # picks up a ZIP from .contextzip/inbox/
cz apply fix.zip      # or point at one directly
cz apply --dry-run    # preview without writing anything

AI tools return ZIPs in every shape: wrapped in an extra folder, relative to a subfolder, flattened, with Windows separators. apply matches each file to its real place in your project anyway.

Every ZIP contextzip makes is kept as a local snapshot (never uploaded). When a reply comes back, three versions of each file are compared: what you sent, what's on disk now, and what came back.

Status	Meaning	Default
New / Modified	New file, or only the AI changed it	Written
Merged	You both changed it, in different places	Written (three-way merge)
Unchanged	Already matches, including changes you already applied	Skipped
Conflict	You both changed the same or neighbouring lines	Needs your call
Partial	The AI returned a cut-down file (// ... rest unchanged)	Needs your call
Moved	The AI moved or renamed it	Written at the new path; the old file is kept unless you say otherwise
Drifted / Deleted / Untracked / Ambiguous / Delete requested	Can't be applied safely without you	Needs your call

When something needs a decision you choose: apply the safe changes now, review side by side in your browser (--review), resolve in VS Code's merge editor (--editor), or apply everything. Line endings never count as a change, redacted secrets are never overwritten with placeholders, and files are only removed with your explicit OK.

Each ZIP also carries a short CONTEXTZIP.md telling the AI how to reply so the answer applies cleanly: complete files, same paths, moves and deletions listed.

Secrets

Secret files are excluded from every project, whatever its stack: .env and .env.*, *.pem, *.key, keystores, SSH private keys, .npmrc, .netrc, cloud credential files, kubeconfigs and Terraform state.

When the AI needs to see which settings exist, include the file on purpose. Keys and comments are kept; values are not:

# .env on disk                          # .env in the ZIP
DATABASE_URL=postgres://u:pw@db/app     DATABASE_URL=[REDACTED]
export API_KEY="sk-live-…"  # prod      export API_KEY="[REDACTED]"  # prod

Spring Boot's application.properties and application.yml are always redacted the same way, because they are config the AI needs and routinely hold live passwords:

# application.properties on disk                       # in the ZIP
spring.datasource.url=jdbc:postgresql://app:pw@db/app   spring.datasource.url=jdbc:postgresql://app:[REDACTED]@db/app
spring.datasource.password=hunter2                      spring.datasource.password=[REDACTED]
jwt.secret=${JWT_SECRET:dev-secret}                     jwt.secret=${JWT_SECRET:[REDACTED]}

When the file comes back, apply keeps your real values. Set limits.redact_secrets: true to also mask API keys, tokens and private-key blocks hardcoded in ordinary files. Before sharing a sensitive project, cz --dry-run --verbose shows exactly what will go in.

Stacks

contextzip recognises a stack from marker files (package.json, pyproject.toml, pom.xml, *.csproj, composer.json, pubspec.yaml, Cargo.toml, go.mod) and the dependencies they list. It looks a couple of levels deep and reads workspace files, so a monorepo with a React frontend and a Spring Boot backend gets both rule sets. A folder of scripts with no project file is recognised by its file types.

Ecosystem	Frameworks recognised	Examples of what's excluded
JavaScript / TypeScript	Next.js, Nuxt, SvelteKit, Astro, Remix, Gatsby, Angular, Vue, Svelte, Vite, NestJS, Expo, React Native, Electron, Tauri, Bun, Deno	node_modules/, .next/, .nuxt/, .svelte-kit/, dist/, coverage/, lockfiles, *.min.js
Python	Django, FastAPI, Flask, Jupyter	__pycache__/, .venv/, *.pyc, .pytest_cache/, *.egg-info/, model weights
Java / Kotlin / Scala / Clojure	Spring Boot, Android	target/, build/, .gradle/, *.class, *.jar, build wrappers, IDE files
C# / .NET	Unity	bin/, obj/, .vs/, *.nupkg; for Unity: Library/, *.meta, scenes and prefabs
PHP	Laravel, Symfony, WordPress	vendor/, composer.lock, storage/framework/, var/, WordPress core and wp-config.php
Swift / Dart	Xcode, SwiftPM, CocoaPods, Flutter	.build/, DerivedData/, Pods/, *.pbxproj, .dart_tool/, *.g.dart
C / C++	CMake, Meson, Autotools, MSBuild, Bazel	build/, cmake-build-*/, CMakeCache.txt, *.o, *.obj, bazel-*/
Rust, Go, Zig, Nim		target/, Cargo.lock, vendor/, go.sum, zig-out/
Ruby	Rails, Jekyll	vendor/bundle/, tmp/, log/, storage/, _site/
Elixir / Erlang	Phoenix	_build/, deps/, mix.lock, *.beam
Haskell, OCaml, R, Julia, Lua, Perl		dist-newstyle/, _build/, renv/library/, Manifest.toml
Other	Terraform, Foundry, Hardhat, Godot, Unreal Engine, Hugo	*.tfvars, .terraform.lock.hcl, out/, artifacts/, .godot/, Intermediate/

cz stacks lists all 62, and cz stacks laravel shows everything one leaves out. Missing yours? Request it, or add it: one table entry and one test case.

More ways to use it

In your browser

contextzipcli.com runs the same code as the CLI, in the page.

• Drop a folder and it's packaged locally. Your files never leave your machine.
• Paste a repo link to package a public repository. Shortcut: put contextzipcli.com/ in front of a repo URL, as in contextzipcli.com/github.com/user/repo.
• Apply the AI's reply to your folder (Chrome and Edge): pick the folder and the ZIP, review the plan, and the safe changes are written for you.

A repository, without cloning it

cz github.com/pallets/click
cz https://github.com/pallets/click/tree/main/src     # one branch, one folder
cz gh:you/private-repo --ref dev
cz gitlab.com/group/project                           # or gl:group/project
cz bitbucket.org/team/repo                            # or bb:team/repo

contextzip downloads one commit through the host's API and packages it like any other project. Private repos use GITHUB_TOKEN (or your gh login), GITLAB_TOKEN or BITBUCKET_TOKEN; a token is only ever sent to its own host. For a GitHub repo, cz apply reply.zip --pr commits the AI's changes and opens a pull request, forking first if you can't push.

VS Code extension

contextzip for VS Code bundles the CLI, so it works without Python. Package the project, a selection, your git changes or a GitHub repo from the Explorer's right-click menu. When an AI's ZIP lands in your Downloads, the extension offers to apply it: every file's status shows in the AI Changes view, safe changes apply in one step, and conflicts open in the three-way merge editor.

MCP server for AI agents

pip install "contextzip[mcp]"      # Python 3.10+

{"mcpServers": {"contextzip": {"command": "contextzip", "args": ["mcp"]}}}

An agent can then package a project or a repository, preview and apply a reply, list snapshots and open a pull request. See CLI.md for every tool.

Let AI pick the files

cz --prompt "add rate limiting to the login endpoint"

Describe the task and Gemini picks only the files that matter; the ZIP also gets a prompt.txt describing the task. It needs a free Gemini API key, which contextzip walks you through the first time. Only file paths and sizes plus your prompt are sent, never file contents. If Gemini is rate-limited, a local keyword-based selector takes over.

Choose files by hand

cz pick

contextzip pick · my-app                    44 of 312 files · 186 KB · 46,210 tokens
Fits  Claude ≈23% · ChatGPT 36% · Gemini ≈5%
──────────────────────────────────────────────────────────────────────────────────────
 ▾  [x] src/                                  38 files                    41,300
    ▸  [x] app/                               12 files                    18,200
    ▸  [-] components/                        9 of 14 files               12,100
       [x] main.tsx                                                          420
 ▸  [ ] docs/                                 left out
    [ ] big-export.json                       large                       2.1 MB

A full-screen tree in the terminal: tick files and folders with the space bar (or the mouse), filter with /, and watch the token total and the model fit change as you go. Enter packages exactly what's ticked; w saves it as the project's default. Ticking a folder never drags in what the rules or .gitignore leave out (node_modules/, .env); tick such a file directly to bring it in, and secret files are still redacted. cz include and cz exclude with nothing after them open it too.

Or set include/exclude in a browser tab:

cz config --ui

A local browser tab where you tick what goes in the ZIP. It shows how big each folder is, points out what is probably not code, and saves your choices to .contextzip/config.json. The server binds to 127.0.0.1 only, needs a one-time session token and shuts itself down when you're done.

Package the moment something breaks

cz watch -- npm run dev

contextzip runs your command and watches its output. When a stack trace appears (Python, Node.js and Java/Kotlin errors are recognised), press D to get a ZIP with the error, a ready-made prompt and the source files named in the trace.

Command reference

Command	What it does
cz	Detect the stack, leave out the noise and package the project
cz pick	Choose files in a terminal tree, with live token totals
cz include PATH…	Package only these paths
cz exclude PATTERN…	Package everything except these patterns
cz --git-changes	Package only modified, staged and untracked files
cz --prompt "task"	Let Gemini pick only the files relevant to a task
cz tokens [PATH…]	Show where the tokens are, and whether they fit Claude, ChatGPT and Gemini
cz github.com/user/repo	Package a GitHub, GitLab or Bitbucket repository without cloning it
cz apply [ZIP]	Write an AI-returned ZIP back into your project, safely
cz apply ZIP --pr	Send an AI's reply to a GitHub repo back as a pull request
cz snapshots	List what you've sent, so a reply can be merged against it
cz init	Set a project up: see what would be packaged and save the defaults
cz stacks	List the languages and frameworks contextzip recognises
cz doctor	Check that everything works on this machine
cz completions --install	Tab completion for bash, zsh, fish or PowerShell
cz watch -- COMMAND	Run a command and package debug context when an error appears
cz config …	Gemini key, workspace location and the visual config UI
cz mcp	Run the MCP server for AI agents
cz update	Update to the latest release
cz setup-path	Put cz on your PATH when pip didn't

Flag	Short	Description
--include PATH	-i	Only include files under these paths. Naming an excluded path (like .env) brings it back. Repeatable.
--exclude PATTERN	-e	Extra exclusion patterns (gitignore syntax). Repeatable.
--prompt TEXT	-p	Let Gemini select files relevant to this task.
--git-changes		Only include files git reports as changed.
--dry-run	-n	Show what would be included without creating the ZIP.
--output FILE	-o	Write the ZIP to this exact path.
--no-clipboard		Don't copy the ZIP to the clipboard.
--no-gitignore		Ignore .gitignore and use only the built-in rules.
--verbose	-v	List every included and excluded file.
--here		Only package the folder you're in.
--from REPO		Package a remote repository (or just put the repo first: cz github.com/user/repo).
--ref REF		Branch, tag or commit for --from.
--max-tokens N		A token budget (150k, 1.5m). Over it, nothing is written.
--trim		With a budget: leave out generated files, data, tests and docs, in that order, until it fits.
--for MODEL		Show whether the ZIP fits this model: claude, chatgpt or gemini. Repeatable. Default: all.
--plain		One line per step, no bars or colour. Also what you get when the output is piped.
--json		Print one JSON object instead of terminal output, for editors and scripts.

Every command supports -h. For every flag of every subcommand, see CLI.md or the online reference.