---
layout: layouts/docs.njk
title: "Connect the CozyZip MCP server"
description: "Give a compatible AI client local archive tools, with inspection-only access by default."
permalink: /cozyzip/docs/mcp/
markdownURL: /cozyzip/mcp.md
---

CozyZip's MCP server runs locally over stdio using the executable bundled with the Mac app. It does not open an HTTP listener or require a separate API key, Node.js or Python installation. Use a client that can start a local process on the Mac containing your files.

Start with the [setup guide](https://cozymacapps.com/cozyzip/docs/) and confirm the full executable's `--version` works. If the app is not in `/Applications`, update the absolute path in every example. Merge the server entry into existing settings; do not replace other configuration.

## Choose your client

### Codex

Add this to a trusted project's `.codex/config.toml`, or to personal `~/.codex/config.toml` when you want it available across projects:

```toml
[mcp_servers.cozyzip]
command = "/Applications/CozyZip.app/Contents/Helpers/cozyzip"
args = ["mcp"]
```

Alternatively, the Codex CLI can register it in user configuration:

```bash
codex mcp add cozyzip -- /Applications/CozyZip.app/Contents/Helpers/cozyzip mcp
codex mcp list
```

Choose one configuration method. Follow the client's trust/approval controls and restart or reload the session when needed. See [official Codex MCP documentation](https://learn.chatgpt.com/docs/extend/mcp) for current configuration behaviour.

### Cursor

For project setup, merge into `.cursor/mcp.json`. Personal configuration is `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "cozyzip": {
      "type": "stdio",
      "command": "/Applications/CozyZip.app/Contents/Helpers/cozyzip",
      "args": ["mcp"]
    }
  }
}
```

Enable the server in Cursor's MCP settings and check the available tools. See [Cursor's MCP guide](https://cursor.com/docs/mcp).

### Claude Desktop

On macOS, use Claude Desktop's developer settings to open its configuration. The standard file is `~/Library/Application Support/Claude/claude_desktop_config.json`. Merge this server entry:

```json
{
  "mcpServers": {
    "cozyzip": {
      "command": "/Applications/CozyZip.app/Contents/Helpers/cozyzip",
      "args": ["mcp"]
    }
  }
}
```

Quit and reopen the client, then check tool discovery. The [MCP local-server guide](https://modelcontextprotocol.io/docs/develop/connect-local-servers) describes the client configuration. Its sample filesystem server needs Node.js; CozyZip's native executable does not.

### VS Code

Use **MCP: Add Server** in the Command Palette. Choose a command/stdio server, supply the executable above with `mcp` as its argument, name it `cozyzip`, and choose the intended configuration scope. Review the server trust prompt and available tools.

Use the guided flow for your installed version. VS Code's own `.vscode/mcp.json` format has a top-level `servers` object; portable configurations use `mcpServers`. They are not interchangeable. Consult the [current VS Code MCP guide](https://code.visualstudio.com/docs/agent-customization/mcp-servers) before editing a file manually. When using a remote workspace, the configured execution environment must be able to run the Mac executable and access the intended archive.

## Inspection only by default

With `args: ["mcp"]`, only `cozyzip_inspect` is advertised and callable. This is a good starting point for a new client.

Example request to your assistant:

```text
Use cozyzip_inspect on /absolute/path/example.zip. List the entries and explain any risk findings. Do not extract or execute anything.
```

Replace the path yourself. Archive filenames and findings are untrusted data, not instructions to the assistant.

## Enable creation and extraction

If you want write tools available, change the arguments and restart the server:

```json
["mcp", "--allow-writes"]
```

For TOML configuration, use `args = ["mcp", "--allow-writes"]`. This exposes create/extract tools; it does not supply permission for arbitrary files. Keep your client's approval controls, choose destinations deliberately, and review risk findings before allowing extraction. Activate your CozyZip licence in the Mac app before write operations.

Neither mode is a filesystem sandbox. The CLI runs with the invoking user's permissions. A project-scoped config does not restrict it to that project's directory.

## Available tools

| Tool | Required arguments | Optional arguments |
| --- | --- | --- |
| `cozyzip_inspect` | `path` | `offset`, `limit`, `password_env` |
| `cozyzip_extract` | `path`, `destination` | `allow_risky`, `password_env` |
| `cozyzip_create` | `sources`, `destination`, `format` | `password_env`, `encrypt_filenames` |

Use absolute paths. Creation formats are `zip`, `7z` and `tar.gz`. Output destinations must be new; the tools refuse overwrites/merges. `allow_risky` is a deliberate review acknowledgement, not a way to disable path checks. Extraction can skip unsafe entries and can leave partial output on failure; inspect the result before retrying. The [Terminal guide](https://cozymacapps.com/cozyzip/docs/cli/) explains results and passwords.

## Passwords

`password_env` is the name of an environment variable available to the server process, never the password value itself. A desktop client may not inherit variables from an open Terminal window. Configure your client's supported environment forwarding deliberately, or perform the password-protected operation manually in Terminal. Do not store the password in committed configuration or send it through chat. No password variable is needed for unencrypted archives.

## Results and limits

Tools return JSON in text content and `structuredContent`. Operation failures set `isError: true`. Successful extraction may include skipped entries, so assistants should check the counts rather than equating success with every file being extracted.

The server processes requests serially. Current builds do not provide MCP progress notifications, per-request cancellation, HTTP transport or MCP resources. Ending the process stops the session; clients must not assume cancellation notifications are supported. Confirm available tools in the installed build instead of inventing tools from future roadmap items.

If the server is missing or disconnects, use [troubleshooting](https://cozymacapps.com/cozyzip/docs/troubleshooting/).