MCP 服务器

cozi-calendar-chatgpt

Read-only MCP server that lets ChatGPT query a live Cozi family calendar via its iCalendar feed, exposing tools for events, conflicts, and availability.

README

Cozi for ChatGPT

An unofficial, read-only MCP server that lets ChatGPT query a live Cozi family calendar through Cozi's published iCalendar (ICS) feed.

The private MVP is deployed on Cloudflare Workers and connected to ChatGPT as a developer plugin named Cozi.

What it does

The MCP server exposes seven read-only tools:

list_family_members — list family members inferred from Cozi event prefixes.
list_events — return events in a date range, optionally filtered by person.
get_next_event — return the next upcoming event, optionally for one person.
search_events — search titles, locations, descriptions, and participant prefixes.
find_conflicts — return overlapping events in a date range.
find_free_time — find open windows for one or more people.
availability_summary — compare busy versus free calendar time across people without double-counting overlapping events.

The calendar layer handles:

timed and all-day events
RRULE recurrence expansion
EXDATE exclusions
Cozi participant prefixes such as Michael/Jackson: or All:
America/Los_Angeles and other IANA timezone-aware output
whitespace cleanup and normalization
overlapping-event union for availability calculations

Example prompts

@Cozi What's on the family calendar today?
@Cozi What is Jackson's next event?
@Cozi What is Hannah doing today?
@Cozi Are there any calendar conflicts this weekend?
@Cozi Find a 90-minute free block for Michael and Jackson this Saturday between 9 AM and 8 PM.
@Cozi Who has the most free time this week?

Architecture

Cozi calendar
    |
    | private published ICS URL
    v
Cloudflare Worker
    |
    | validate + fetch + parse
    v
Calendar engine
    |
    | deterministic structured MCP tools
    v
ChatGPT

The Worker is stateless. It fetches the configured Cozi ICS URL on demand and exposes structured, read-only MCP actions to ChatGPT.

See docs/architecture.md for more detail.

Security model

The Cozi feed URL is effectively a read credential to the family calendar. Never commit it.

Production expects it as a Cloudflare Worker runtime secret named:

COZI_CALENDAR_URL

For local development, copy .dev.vars.example to .dev.vars and replace the placeholder with a private test feed URL. .dev.vars is gitignored.

The Worker accepts only HTTPS URLs on the exact rest.cozi.com host with a Cozi iCalendar-feed path. Redirects are handled manually and are not automatically followed to another host. The configured feed URL is never returned by an MCP tool.

Local development

Requirements:

Node.js 20+
npm
a private Cozi calendar feed URL for live testing

npm install
npm test
npm run check

Run locally:

cp .dev.vars.example .dev.vars
# edit .dev.vars with your private Cozi URL
npm run dev

Local MCP endpoint:

http://localhost:8787/mcp

Cloudflare deployment

The repository is connected to Cloudflare Workers Builds. Pushes to main automatically deploy using:

npx wrangler deploy

The Worker configuration lives in wrangler.jsonc and the production secret is managed in Cloudflare, not GitHub.

Health endpoint:

https://<worker>.<account>.workers.dev/health

MCP endpoint:

https://<worker>.<account>.workers.dev/mcp

ChatGPT connection

The private developer connection uses the HTTPS /mcp endpoint with no MCP authentication because the single private Cozi feed URL is stored server-side as a Cloudflare secret.

That is appropriate only for the private MVP. A public release must add per-user connection/authentication and secure per-user storage so every user supplies only their own Cozi calendar feed.