# mjucius-cozi_mcp [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/mjucius/cozi_mcp  
**GitHub Stars:** 6  
**npm Downloads (last month):** 1002  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mjucius-cozi-mcp

## Description
Manage your family's calendars and lists in Cozi. View, create, and update appointments; organize…

## Tools
Capabilities this server exposes over MCP:

- **family_members** — List family members. Use the `id` for appointment attendees. Returns: [{id, name, color?}].
- **get_lists** — Summarize all lists (no items). Optionally filter by 'shopping' or 'todo'. Returns: [{id, title, type, item_count, completed_count}].
- **get_list_items** — Items in one list. Excludes completed items by default. Returns: [{id, text, status, position?}].
- **create_list** — Create a list ('shopping' or 'todo'). Returns: {id, title, type}.
- **rename_list** — Rename a list; its items stay as they are. Returns: {id, title, type}.
- **delete_list** — Delete a list. Returns true on success.
- **add_item** — Add an item to a list. Returns: {id, text}.
- **update_item** — Update an item's text and/or completion status. Pass `text`, `completed`, or both. When both are provided the text is updated first then status is updated as a separate request — these are NOT atomic. Returns: {id, text, status}.
- **remove_items** — Remove items from a list. Returns true on success.
- **get_calendar** — Appointments for one month. Returns: [{id, subject, day, all_day, start?, end?, end_day?, attendees?, location?, notes?, reminders?, kind?, read_only?, source?, recurring?, recurrence?, series_start?, series_end?, skipped_days?}]. `day` is the day the entry happens; `end_day` appears only on multi-day events, which are listed in every month they overlap, so `day` may fall outside the month asked for. A recurring series (`recurring: true`) is listed once per occurrence in the month, as Cozi itself expands it: each entry carries the series `id`, its own `day` (and `end_day` when the occurrence spans days), and `series_start`. Occurrences deleted in Cozi are already left out (and named in `skipped_days`); a series with no occurrence left in the month is not listed. `kind` marks items that are not plain appointments (e.g. "birthday"); `read_only` items (holidays, subscribed calendars, with `source` naming the calendar) cannot be changed. `reminders` are minutes before the start.
- **search_calendar** — Find appointments by words in their subject, across months (Cozi's own search, the one in its app). Use it for "when is the dentist?" instead of paging through months. Returns: {appointments: [{...same fields as get_calendar, last_day?, next_days?}], more?}. A recurring series is one entry with `last_day` (latest past occurrence) and `next_days` (up to 10 upcoming). Cozi searches from a few years back onward, and an appointment created in the last few seconds may not be found yet; `more: true` means it found more than this first page, so narrow the query.
- **today** — Current date, weekday and time on the user's machine. Returns: {date, weekday, time, timezone}. Call it before turning 'tomorrow' or 'this Saturday' into the ISO dates the calendar tools take when you have not called another Cozi tool yet; every Cozi tool result also carries this time.
- **create_appointment** — Create a calendar appointment. `start` and `end` are ISO datetimes (e.g. '2026-06-15T10:00:00'). For all-day events (all_day=true) a bare date (e.g. '2026-06-15') is also accepted and `end` may equal `start`; a bare date on a timed event is an error. For a multi-day event put `end` on a later date — the span is preserved, and the result reports it as `end_day`. `end` before `start` is an error. For attendees, call family_members() first and pass those `id` values. For a repeating event pass `repeat`; `start`/`end` are then its first occurrence.
- **update_appointment** — Partial-update an appointment. The Cozi PUT semantics replace ALL fields, so this tool first fetches the existing appointment from the (year, month) page and merges your changes — only fields you pass are altered. To switch a timed appointment to all-day pass all_day=true; to switch to timed pass new start/end. Passing `end` re-spans the event against its (possibly newly set) start day, so an `end` on a later date makes it multi-day and one on the start day collapses it back; passing `start` alone moves the event and keeps its length, and all_day=true preserves the span. A bare date (e.g. '2026-06-15') is accepted for `start`/`end` when the event is, or is being made, all-day; on a timed event it is an error. A recurring series (`recurring: true` in get_calendar) needs `scope`: 'this' changes only the occurrence on `occurrence_day` (Cozi stores it as its own appointment, returned here), 'this_and_following' changes it and every later one (returned as the new series), 'series' changes every occurrence and keeps the rule unless `repeat` replaces it. `repeat` also turns a one-off into a series. Holidays, subscribed calendars and birthdays cannot be changed.
- **delete_appointment** — Delete an appointment. Returns true on success; errors if the id is not on the (year, month) page. A recurring series (`recurring: true` in get_calendar) needs `scope`: 'this' removes only the occurrence on `occurrence_day`, 'this_and_following' ends the series before it, 'series' removes every occurrence, past and future. Confirm a 'series' delete with the user first. Holidays, subscribed calendars and birthdays cannot be deleted.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mjucius-cozi-mcp": {
    "command": "npx",
    "args": ["-y","@mjucius/cozi-mcp"],
    "env": {
      "COZI_USERNAME": "",
      "COZI_PASSWORD": ""
    }
  }
}
```

**Requires environment variables:** `COZI_USERNAME`, `COZI_PASSWORD` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What mjucius-cozi_mcp does

Cozi Family Organizer exposes calendars, family members, shopping lists, and to-do lists through MCP. The server can inspect appointments by month or search Cozi's calendar across months, then create, update, or delete appointments when write access is enabled. It also supports list and item operations, including creating or renaming lists, adding items, marking items complete, and removing items.

Calendar results include details such as dates, times, attendees, locations, notes, reminders, recurrence information, and whether an entry is read-only. Family-member IDs can be retrieved before creating or updating appointment attendees.

## How it works

Each user runs an instance connected to their own Cozi account. The local MCPB and npx modes send credentials to Cozi's API at `https://rest.cozi.com`; credentials are not sent to the project author. The Cloudflare option stores the account session and password within the user's own Cloudflare setup and is intended for Claude access across web, phone, and desktop.

The default tool surface is read-write. Setting `COZI_READ_ONLY=true` exposes only `family_members`, `get_lists`, `get_list_items`, `get_calendar`, `search_calendar`, and `today`.

For natural-language dates, call `today` before converting terms such as “tomorrow” into ISO dates when no other Cozi tool has been called. Recurring appointments require an explicit scope when updated or deleted. Updating both an item's text and completion state uses separate requests rather than one atomic operation.

## Setup and configuration

For Claude Desktop, download the latest MCPB from the project's releases and install it. This path does not require Node, npm, or Python, and prompts for the Cozi username and password.

For other MCP clients, configure an npx server using the `@mjucius/cozi-mcp` package:

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

The npx method requires Node.js 20 or newer and downloads the package on first use. Credentials are read when the process starts, so restart the MCP client after changing them. A Cloudflare deployment follows a separate setup guide and works with Claude only.

## Tools and capabilities

- Inspect family members for appointment attendee IDs.
- Summarize shopping and to-do lists, then retrieve their items.
- Create, rename, and delete lists.
- Add, update, and remove list items.
- Read one month of calendar entries or search appointments across months.
- Create all-day, timed, multi-day, and repeating appointments.
- Partially update appointments while preserving fields not supplied.
- Delete individual occurrences, future occurrences, or full recurring series.
- Retrieve the local machine's date, weekday, time, and timezone.

## Limitations and notes

Cozi does not provide OAuth; authentication uses a username and password. Holidays, subscribed-calendar entries, and birthdays are read-only and cannot be changed or deleted. Deleting a complete recurring series should be confirmed with the user before execution.

Calendar deletion and updates require the appointment to be available on the relevant year-and-month page. A newly created appointment may not appear in Cozi search immediately. Cozi authentication also applies exponential backoff after five consecutive failed logins.

The project is unofficial and MIT licensed. Its single-user design means access is based on the local process or the configured Cloudflare instance and the associated Cozi credentials.

_Full upstream README: https://allmcps.com/mcp/mjucius-cozi-mcp/readme_