{
  "markdown": "# mcp-zip\n\n<!-- mirror-seo:start -->\n\n**MCP server for zip archives: create, inspect and extract.** Make a zip, look inside one, and unpack one, entirely on your machine.\n\nWorks with Claude Desktop, Claude Code, Cursor and any Model Context Protocol client. Runs on your own machine, or hosted with no install.\n\n## Install\n\n**Hosted, nothing to install.** Get a token from <https://mcp.zovo.one/mcp/connect> (the connect page) or <https://mcp.zovo.one/mcp/token> (the same token as JSON); a free anonymous one is issued on the spot and a Pro key works the same way. Then point an MCP client at `https://mcp.zovo.one/mcp/zip` over streamable-http and send the token as `Authorization: Bearer <token>`.\n\nIf your client cannot set headers, put the token in the path instead: `https://mcp.zovo.one/mcp/zip/t/<token>`. Both forms work. The bare URL with no token answers 401 on `tools/call`, so the token is not optional.\n\n**Claude Desktop, one click.** Download `zip.mcpb` from the [latest release](https://github.com/theluckystrike/mcp-servers/releases/latest) and double-click it.\n\n**From source.** The mirror is self-contained: every `@theluckystrike/*` dependency is vendored, so a fresh clone builds with no extra setup.\n\n```sh\ngit clone https://github.com/theluckystrike/mcp-zip.git\ncd mcp-zip\nnpm install && npm run build\n```\n\nThen point your client at the built entry point:\n\n```json\n{\n  \"mcpServers\": {\n    \"zip\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/mcp-zip/dist/index.js\"]\n    }\n  }\n}\n```\n\n> `@theluckystrike/mcp-zip` is **not published on npm yet**, so an `npx -y @theluckystrike/mcp-zip` command will fail. The three paths above are the working ones and each is exercised by CI.\n\n![zip demo](https://raw.githubusercontent.com/theluckystrike/mcp-servers/main/assets/demo-zip.gif)\n\nRead-only mirror of [mcp-servers/servers/zip](https://github.com/theluckystrike/mcp-servers/tree/main/servers/zip). See [MIRROR.md](MIRROR.md).\n\n<!-- mirror-seo:end -->\n\nMake a zip, look inside one, and unpack one, in the conversation you are already in. Pack a folder with a glob\n(`**/*.csv`, everything except `node_modules`). Read the one README out of an archive without unpacking it.\nAsk what is inside a zip somebody sent you and be told before you open it: absolute paths, `..`, symlinks,\nduplicate names, and the entry that claims to be 200 MB inside a 199 KB file. Bundle a month of invoices,\nquotes and exports into one file to send to an accountant. Everything runs on your machine: no upload, no\naccount, no API key, and no network call of any kind.\n\n\nnpm publish for `@theluckystrike/mcp-zip` is pending, so `npx -y @theluckystrike/mcp-zip` returns 404 today. Until then, the `.mcpb` one-click bundle or a clone+build is the working path.\n\n## Install\n\nClaude Desktop, `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or\n`%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"zip\": { \"command\": \"npx\", \"args\": [\"-y\", \"@theluckystrike/mcp-zip\"] }\n  }\n}\n```\n\nClaude Code:\n\n```sh\nclaude mcp add zip -- npx -y @theluckystrike/mcp-zip\n```\n\nCursor, `.cursor/mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zip\": { \"command\": \"npx\", \"args\": [\"-y\", \"@theluckystrike/mcp-zip\"] }\n  }\n}\n```\n\n## Tools\n\n| tool | what it does |\n| --- | --- |\n| `zip_create` | Pack files, or a directory tree with glob patterns, into a new .zip |\n| `zip_list` | Every entry with its size, compressed size and ratio, and everything dangerous in it, flagged |\n| `zip_extract` | Unpack into a directory, with traversal, symlink and zip-bomb guards and a `dry_run` |\n| `zip_add` | Add files to an archive that already exists |\n| `zip_extract_text` | Read one text entry inline, without unpacking anything |\n| `zip_bundle_month` | One month of invoices, quotes and exports from the sibling servers, in one file |\n| `zip_history` | What you have created, and how much of this month's free allowance is left |\n| `license_status`, `license_activate` | Free or Pro, and activating a key |\n\n## Free vs Pro\n\n| | Free | Pro |\n| --- | --- | --- |\n| Archives per calendar month | 20 | Unlimited |\n| Archive size | Up to 25 MB | Unlimited |\n| Entries per archive | Up to 200 | Unlimited |\n| Reading: `zip_list`, `zip_extract`, `zip_extract_text` | Unlimited | Unlimited |\n| Bomb, traversal and symlink guards | Yes | Yes |\n\nReading is never metered. The free tier is a limit on what you *write*, because an archive somebody sent you is\nexactly the one you most need to inspect before opening, and a paywall in front of that would be a paywall in\nfront of the safety check.\n\nGet Pro: **https://mcp.zovo.one/buy/zip** - $19 one time, or $39 for every server in the suite, lifetime.\nKeys verify offline; nothing is sent anywhere.\n\n## Why fflate and not a hand-written writer\n\nThe choice was `fflate` (pure JS, 0 dependencies, synchronous `zipSync`/`inflateSync`) against writing a\nSTORE/DEFLATE writer on `node:zlib`, which is available with no dependency at all.\n\nThe container format is written here either way. This server reads the central directory itself, in\n`src/zipfile.ts`, roughly 200 lines: sizes, names, methods, CRCs, external attributes. It has to, because every\nguard in the server is a decision made from those headers *before* anything is inflated, and a library that\nhands back `{name: bytes}` has already decompressed the bomb by the time you can look at it. So the argument for\na library was never \"it saves me the format\".\n\nWhat is left is the compressor, and that is the part not to write. `node:zlib` would do it, but its raw-deflate\ncalls are async-first, they carry a thread-pool round trip per call, and the sync ones each build a native\nstream; packing 200 small files is 200 of those. fflate's `deflateSync` is a pure-JS implementation with no\nnative handle, it packs 200 files in 74 ms (measured below), and it means the package still has no native build\nstep, which is the rule for this whole suite: `npx` has to work everywhere.\n\nThe trade is stated plainly: fflate builds the archive in one buffer, so this server refuses inputs over\n512 MB rather than pretending to stream, and it does not read ZIP64 (over 4 GB or over 65,535 entries), which is\nrefused by name rather than misread.\n\n## Measured: the file type does not predict the compression ratio, repetition does\n\nEvery file below was zipped at level 6 on this machine. The \"type\" column is what a person would call the file;\nthe ratio is what actually happened.\n\n| file | type | bytes | zipped | ratio |\n| --- | --- | --- | --- | --- |\n| a 12-page invoice from `mcp-pdf` | PDF | 15,125 | 14,118 | **1.07x** |\n| a 400-paragraph contract from `mcp-docx` | DOCX | 9,897 | 7,311 | **1.35x** |\n| 4,000 rows of billing CSV, varied values | CSV | 321,329 | 134,049 | **2.40x** |\n| this server's own `index.ts` | source | 39,498 | 11,938 | 3.31x |\n| `package-lock.json` | JSON | 138,835 | 33,223 | 4.18x |\n| 20,000 lines of an app log | log | 1,603,390 | 106,261 | **15.09x** |\n| 4,000 rows of billing CSV, 40 repeated clients | CSV | 338,549 | 4,094 | **82.69x** |\n| 50 MB of zero bytes | bomb | 52,428,800 | 51,294 | **1022x** |\n\nPDF and DOCX barely move, and that is not a surprise once you look inside them: both are already deflate\ncontainers, so zipping them again is packaging, not compression. Bundling a month of invoices is worth doing for\nthe one file, not for the space.\n\nThe two CSV rows are the interesting pair. Same tool, same shape, same size, **34x apart**: the one with forty\nrepeated client names compresses 82.69x, the one with unique values 2.40x. Nothing about \"it is a CSV\" predicts\nwhich one you have.\n\n## Measured: why the bomb ceiling is 100x and not 50x\n\nA compression bomb is refused by ratio, and the obvious instinct is to set that ceiling low, well under the\n1022x a zeros file reaches. The table above says why that is wrong: a **real** CSV export, of the kind\n`zip_bundle_month` collects from the expense tracker, reached **82.69x**, which is 83% of the way to a 100x\nceiling and well past a 50x one. A ceiling tuned to be comfortably below a bomb would refuse a real monthly\nexport, and the person on the other end would learn to pass `max_ratio` on everything, which turns the guard\noff permanently.\n\nSo the ratio is the *second* guard, not the first. The first is the total: the selected entries' declared\nuncompressed sizes are added up and compared against a ceiling (1 GB by default, `max_total_mb` to change it),\nbecause 200 MB out of a 199 KB file is a decision you can make about the archive as a whole without judging any\nentry. Both are read from the central directory, so refusing a bomb costs no decompression at all:\n\n```\nrefuse a 500 MB bomb (497.8 KB on disk)   3 ms, nothing inflated, out_dir not even created\n```\n\n## Measured: a bounded output buffer is not a bomb guard\n\n`fflate.inflateSync(data, { out: new Uint8Array(n) })` looks like the whole answer: cap the buffer, cap the\ndamage. It is not, and the way it fails is quiet. A 100,000-byte entry inflated into a 10-byte buffer returns\n**10 bytes and throws nothing**. An archive whose header declares 10 bytes for a 100 KB entry would extract as a\n10-byte file, reported as a success, with the truncation invisible.\n\nSo the buffer bounds the memory and the **CRC-32 in the central directory** proves the bytes. Every entry this\nserver writes out is checksummed against the header before it reaches the disk, and a mismatch refuses the entry\nby name. That is the check that turns a lying header from silent data loss into a sentence.\n\n## Timings\n\nM-series laptop, over stdio, per call, cold store:\n\n| operation | measured |\n| --- | --- |\n| `zip_create`, 200 files, 4.0 MB | 74 ms |\n| `zip_list`, 200 entries | 2 ms |\n| `zip_extract`, 200 entries | 47 ms |\n| `zip_extract_text`, one entry | 1 ms |\n| refuse a 500 MB bomb | 3 ms |\n| whole test suite, 38 tests, five files | 3.9 s |\n\n## Privacy\n\nEverything stays on your machine. There is no network code in this server at all: no `fetch`, no HTTP client, no\ntelemetry. Archives are written where you say, and a small register of what was created lives under\n`~/.local/share/mcp-servers/zip/` (or `$XDG_DATA_HOME`). License keys verify offline with a public key.\n\nZip passwords are not supported, and passing one is refused rather than ignored: the classic zip cipher is\nbroken and AES zip encryption is a vendor extension no two tools agree on, so a \"password protected\" archive\nfrom here would be a false promise.\n\nBuilt by [theluckystrike](https://github.com/theluckystrike). Support: support@zovo.one\n",
  "bytes": 10572,
  "sha": "ccc57c261ceb02268983b9d259fc71d34557d2d7692b3b1de9efcd8f00ca9315",
  "repo_slug": "theluckystrike/mcp-zip",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_theluckystrike_mcp_zip_42d969f2/readme"
}