Connect the CozyZip MCP server

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 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:

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

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

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 for current configuration behaviour.

Cursor

For project setup, merge into .cursor/mcp.json. Personal configuration is ~/.cursor/mcp.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.

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:

{
  "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 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 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:

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:

["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 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.