Cozi MCP Server

An unofficial Model Context Protocol server that lets AI assistants like Claude read and update your Cozi Family Organizer lists and calendar.

Each user runs their own instance against their own Cozi account. Your credentials are stored in your MCP client's secure config (Claude Desktop's OS keychain, Smithery's encrypted session config, or your local environment) and never leave your machine — the author of this server has no access to your data.

Install

1. MCPB (recommended for Claude Desktop)

Download the latest .mcpb from the Releases page and double-click to install in Claude Desktop. You'll be prompted for your Cozi username and password — they're stored securely in your OS keychain.

This path requires no Node, npm, or Python install on your machine.

2. Smithery (for other MCP clients)

For Cursor, ChatGPT-style clients, or web agents that connect to Smithery-hosted servers:

Deploy on Smithery.ai →

Configure your Cozi credentials in the Smithery UI; each session runs in isolation with its own credential set.

3. npx (for power users)

Add this to your Claude Desktop claude_desktop_config.json (or any other MCP client config file):

{
  "mcpServers": {
    "cozi": {
      "command": "npx",
      "args": ["-y", "@mjucius/cozi-mcp"],
      "env": {
        "COZI_USERNAME": "you@example.com",
        "COZI_PASSWORD": "your-password",
        "COZI_READ_ONLY": "true"
      }
    }
  }
}

Requires Node 20+. The package will be downloaded on first run.

Set COZI_READ_ONLY=true to expose only read operations. In read-only mode, the server registers family_members, get_lists, get_list_items, and get_calendar; tools that create, update, or delete Cozi data are hidden from MCP clients. Omit the variable, or set it to any value other than 1, true, yes, or on, for the default read-write tool surface.

Troubleshooting

Tools fail with "Authentication failed" even after I corrected my password

COZI_USERNAME and COZI_PASSWORD are read once, when the server process starts. Editing them in your MCP client's settings updates the stored config but does not reach a server that is already running — it keeps presenting the old credentials until it is respawned.

Fully quit and relaunch your MCP client (on macOS, Cmd-Q rather than closing the window). Reloading, reconnecting, or toggling the extension off and on is usually not enough.

How do I tell which version is actually running?

The running server advertises its version in the MCP handshake; your client displays it (Claude Desktop: Settings > Extensions). That is independent of what is in your working tree — installing an MCPB installs whatever is inside the .mcpb file, which is only as current as the last npm run bundle:mcpb. Build the bundle immediately before installing it, or install from a GitHub release.

Repeated failures start returning "Too many failed login attempts"

Five consecutive failed authentications for a username trigger an exponential backoff, capped at 15 minutes; the message states the remaining wait. The counter lives in process memory, so restarting the client clears it.

Trust and Security

Cozi has no OAuth — username/password authentication is the only way the API supports. This server handles that fact honestly:

Per-user, by architecture. Each user runs their own instance against their own Cozi account. There is no shared backend, no proxy, no multi-tenant database. The author of this server never sees anyone's credentials or data.
Credentials live only in your MCP client's secure config. Claude Desktop stores them in your OS keychain. Smithery encrypts them per-session. The npx path reads them from environment variables you set yourself. Nothing is logged, written to disk by this server, or sent anywhere except https://rest.cozi.com.
API surface is constrained. This server only contacts rest.cozi.com for the same endpoints the Cozi web app uses (auth, lists, calendar, family members). The full request/response code lives in src/cozi/ — about 500 lines of TypeScript you can audit yourself.
Open source, MIT licensed. Pin a specific version (@mjucius/cozi-mcp@2.0.0) if you want a stable target, or fork the repo and run your own build if you want zero supply-chain trust.

Security & trust model

This is a single-user server by design. The Cozi credential holder is the principal — there is no separate per-caller authentication gate, because each user runs their own instance against their own Cozi account. Concretely:

stdio (npx / MCPB) trusts the local user. Whoever can launch the process and read the configured COZI_USERNAME / COZI_PASSWORD (or the OS keychain entry) is treated as the account owner. The trust boundary is your machine and its user account.
The Smithery HTTP deployment trusts the session-config credentials as the principal. Whoever supplies valid Cozi credentials in the session config is the authenticated user for that session. There is no additional login layer.
No multi-tenancy. Each user configures their own instance with their own Cozi account. There is no shared backend, no tenant isolation to breach, and no per-caller authentication beyond possession of valid Cozi credentials — which is the same access model as the Cozi web app itself.

Two defensive measures narrow the blast radius of that model:

Time-bounded credential cache. Authenticated clients are cached only for a bounded lifetime, so a rotated or revoked Cozi password stops working rather than being honored indefinitely from a stale cached session.
Failed-login rate limiting. Repeated failed authentication attempts are rate-limited to blunt credential-guessing against the Cozi endpoint.

Tools

The server exposes 12 tools by default, or 4 read-only tools when COZI_READ_ONLY=true (or Smithery/MCPB read-only config) is enabled. Returns are slim dicts with null/empty fields omitted.

Family

family_members() → [{id, name, color?}] — call this first to get attendee IDs for appointments.

Lists

get_lists(list_type?) → [{id, title, type, item_count, completed_count}] — list_type is optional, 'shopping' or 'todo'.
get_list_items(list_id, include_completed=false) → [{id, text, status, position?}].
create_list(name, list_type) → {id, title, type}.
delete_list(list_id) → boolean.

create_list and delete_list are hidden in read-only mode.

Items

add_item(list_id, text, position=0) → {id, text}.
update_item(list_id, item_id, text?, completed?) → {id, text, status} — pass either or both. Non-atomic when both are passed: the text is updated first, then the status.
remove_items(list_id, item_ids) → boolean.

All item tools are hidden in read-only mode.

Calendar

get_calendar(year, month) → [{id, subject, day, all_day, start?, end?, attendees?, location?, notes?}].
create_appointment(subject, start, end, attendees?, all_day=false, notes='', location?) — start and end are ISO datetimes (e.g. '2026-06-15T10:00:00'). For all-day events end may equal start.
update_appointment(appointment_id, year, month, ...) — partial update via fetch-then-merge: pass (appointment_id, year, month) plus any fields to change. Omitted fields are preserved. To switch a timed appointment to all-day pass all_day=true; to switch to timed pass new start/end.
delete_appointment(appointment_id, year, month) → boolean.

create_appointment, update_appointment, and delete_appointment are hidden in read-only mode.

Workflow tip

When creating or updating appointments with specific attendees, call family_members() first and use those id values in the attendees arg. Calendar tools are scoped to a (year, month) page — pass the same year/month back when updating or deleting an appointment from that page.

Migration from v1 (Python)

v2.0 is a Node/TypeScript rewrite of the previous Python implementation, distributed as MCPB / npx / Smithery. The runtime changed AND the tool surface was consolidated — if you have prompts written against v1, update them as follows:

| v1 (Python, 14 tools) | v2 (Node, 12 tools) | |---|---| | get_family_members | family_members | | get_lists_by_type(t) | get_lists(list_type=t) | | update_item_text(...) + mark_item(...) | update_item(text?, completed?) (merged) | | add_item(list_id, item_text, ...) | add_item(list_id, text, ...) (param renamed) | | update_appointment(appointment_obj) | update_appointment(appointment_id, year, month, ...partial) | | update_list (item reordering) | removed | | delete_appointment(id) | delete_appointment(id, year, month) | | get_lists returned nested items | now summary only — fetch items via get_list_items(list_id) |

The legacy v1 Python source is preserved at git tag v1.0.0 for reference.

Development

Requires Node 20+ (see .nvmrc).

nvm use
npm install
npm test               # vitest, 68 tests
npm run typecheck
npm run build          # tsup → dist/
npm run dev            # local stdio dev with COZI_USERNAME / COZI_PASSWORD env vars
npm run playground     # @smithery/cli local playground UI
npm run bundle:mcpb    # produces cozi-mcp.mcpb at repo root

The repo layout:

cozi_mcp/
├── src/
│   ├── server.ts              # MCP server factory (Smithery default export)
│   ├── bin.ts                 # npx + MCPB stdio entry point
│   ├── instructions.ts
│   ├── cozi/                  # Inlined Cozi HTTP client (no separate npm package)
│   └── tools/                 # 12 MCP tools
├── tests/                     # vitest, mocks CoziClient at the boundary
├── manifest.json              # MCPB manifest (Claude Desktop)
├── smithery.yaml              # Smithery deploy manifest
└── package.json

The Cozi HTTP client is inlined under src/cozi/ rather than published as a separate npm package — it's small, only useful for this MCP server, and avoids the supply-chain surface area of a separate dependency. If you'd prefer the Python equivalent for your own projects, see py-cozi-client.

Acknowledgments

The ?apikey=coziwc|v…_production requirement on the Cozi auth endpoint was reverse-engineered from the live my.cozi.com web bundle by Wetzel402/py-cozi PR #3. Without that discovery, every login attempt from a server environment fails with a misleading 401 regardless of credential validity.
Built on the Model Context Protocol and its TypeScript SDK by Anthropic.

Trademark and affiliation

Cozi and the Cozi logo are trademarks of Cozi Group Inc. This project is unofficial and not affiliated with, endorsed by, or sponsored by Cozi Group Inc. Use of the Cozi API is at your own risk and subject to Cozi's Terms of Service.

License

MIT — see LICENSE.

Contributing

PRs welcome. Please run npm test and npm run typecheck before submitting.

cozi_mcp