mjucius-cozi_mcp

Cozi MCP サーバー

AI アシスタントが Cozi Family Organizer のリストやカレンダーを読み取り、更新できるようにする、非公式の Model Context Protocol サーバーです。

各ユーザーは、自分の Cozi アカウントに接続する独自のインスタンスを実行します。認証情報は MCP クライアントのセキュアな設定（Claude Desktop の OS キーチェーン、またはローカル環境）に保存され、マシンの外に送信されることはありません。このサーバーの作成者がデータにアクセスすることもありません。

インストール

1. MCPB（Claude Desktop に推奨）

リリースページから最新の .mcpb をダウンロードし、ダブルクリックして Claude Desktop にインストールします。Cozi のユーザー名とパスワードを求められます。これらは OS キーチェーンに安全に保存されます。

この方法では、マシンに Node、npm、Python をインストールする必要はありません。

2. npx（その他の MCP クライアント）

Claude Desktop の claude_desktop_config.json（またはその他の MCP クライアント設定ファイル）に次の内容を追加します。

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

Node 20 以降が必要です。パッケージは初回実行時にダウンロードされます。

読み取り操作のみを公開するには、COZI_READ_ONLY=true を設定します。読み取り専用モードでは、サーバーは family_members、get_lists、get_list_items、get_calendar、search_calendar、today を登録し、Cozi データを作成、更新、または 削除するツールは MCP クライアントから非表示になります。変数を省略するか、1、true、yes、on 以外の値を設定すると、 デフォルトの読み書き可能なツール構成になります。

トラブルシューティング

パスワードを修正したのに、ツールで「Authentication failed」と表示される

COZI_USERNAME と COZI_PASSWORD は、サーバープロセスの起動時に一度だけ読み込まれます。 MCP クライアントの設定でこれらを編集すると、保存されている設定は更新されますが、 すでに実行中のサーバーには反映されません。サーバーを再起動するまで、古い認証情報が使われ続けます。

MCP クライアントを完全に終了してから、再起動してください（macOS ではウィンドウを閉じるのではなく、Cmd-Q を使います）。 再読み込み、再接続、または拡張機能のオフとオンの切り替えだけでは、 通常不十分です。

実際にどのバージョンが実行されているか確認するには？

実行中のサーバーは MCP ハンドシェイクでバージョンを通知し、クライアントに表示されます（Claude Desktop の場合：Settings > Extensions）。これは 作業ツリーにある内容とは別です。MCPB をインストールすると、.mcpb ファイルに含まれるものがインストールされます。その内容が最新かどうかは、最後に実行した npm run bundle:mcpb の時点によって決まります。 インストールの直前にバンドルをビルドするか、GitHub のリリースからインストールしてください。

失敗が繰り返されると「Too many failed login attempts」と表示される

ユーザー名に対して認証が5回連続で失敗すると、指数バックオフが発生し、最大15分まで延長されます。メッセージには残りの待ち時間が表示されます。 カウンターはプロセスメモリ内にあるため、クライアントを再起動するとリセットされます。

信頼とセキュリティ

Cozi は OAuth に対応していません。API がサポートする認証方法はユーザー名とパスワードのみです。このサーバーはその事実を隠さずに扱います。

• アーキテクチャ上、ユーザーごとに分離されています。 各ユーザーは、自分の Cozi アカウントに接続する独自のインスタンスを実行します。共有バックエンドも、プロキシも、マルチテナントデータベースもありません。このサーバーの作成者が、誰かの認証情報やデータを見ることはありません。
• 認証情報は MCP クライアントのセキュアな設定にのみ保存されます。 Claude Desktop は認証情報を OS キーチェーンに保存します。npx を使う方法では、自分で設定した環境変数から読み取ります。このサーバーによってログに記録されたり、ディスクに書き込まれたりすることはなく、https://rest.cozi.com 以外に送信されることもありません。
• API の利用範囲は限定されています。 このサーバーが rest.cozi.com に接続するのは、Cozi のウェブアプリが使用するものと同じエンドポイント（認証、リスト、カレンダー、家族メンバー）のみです。リクエストとレスポンスを処理するコードは src/cozi/ にあり、約500行の TypeScript なので、自分で監査できます。
• オープンソースで、MIT ライセンスです。 安定した対象を使いたい場合は、特定のバージョン（@mjucius/[email protected]）を指定してください。サプライチェーンを完全に信頼せずに使いたい場合は、リポジトリをフォークして独自にビルドしてください。

セキュリティと信頼モデル

これは設計上、シングルユーザー向けのサーバーです。Cozi の認証情報を持つユーザーが本人であり、呼び出し元ごとの個別の認証ゲートはありません。各ユーザーが自分の Cozi アカウントで自身のインスタンスを実行するためです。具体的には次のとおりです。

• stdio（npx / MCPB）はローカルユーザーを信頼します。 プロセスを起動し、設定された COZI_USERNAME / COZI_PASSWORD（または OS キーチェーンのエントリー）を読み取れる人は、アカウント所有者として扱われます。信頼境界は、ご利用のマシンとそのユーザーアカウントです。
• マルチテナントではありません。 各ユーザーは、自分の Cozi アカウントを使って自身のインスタンスを設定します。共有バックエンドはなく、侵害されるテナント分離もありません。有効な Cozi 認証情報の所持以外に呼び出し元ごとの認証もありません。これは Cozi のウェブアプリ自体と同じアクセスモデルです。

このモデルによる影響範囲を限定するため、2 つの防御策を設けています。

• 有効期間を制限した認証情報キャッシュ。 認証済みクライアントは有効期間を限定してキャッシュされるため、Cozi のパスワードを変更または失効させると、古いキャッシュ済みセッションが期限なく使われるのではなく、機能しなくなります。
• ログイン失敗時のレート制限。 認証の失敗が繰り返された場合にレートを制限し、Cozi エンドポイントに対する認証情報の推測を抑制します。

ツール

サーバーは、デフォルトで 15 個のツールを公開します。COZI_READ_ONLY=true（または MCPB の読み取り専用設定）が有効な場合は、読み取り専用ツールを 6 個公開します。戻り値は簡潔な dict で、null や空のフィールドは省略されます。

家族

• family_members() → [{id, name, color?}] — 予定の参加者 ID を取得するため、最初に呼び出してください。

リスト

• get_lists(list_type?) → [{id, title, type, item_count, completed_count}] — list_type は省略可能で、'shopping' または 'todo' を指定します。
• get_list_items(list_id, include_completed=false) → [{id, text, status, position?, header?}] — header: true は項目ではなく、セクション見出し（例：「PRODUCE」）であることを示します。
• create_list(name, list_type) → {id, title, type}。
• rename_list(list_id, title) → {id, title, type} — 項目は変更されません。
• delete_list(list_id) → boolean。

読み取り専用モードでは、create_list、rename_list、delete_list は非表示になります。

項目

• add_item(list_id, text, position=0) → {id, text}。
• update_item(list_id, item_id, text?, completed?) → {id, text, status} — どちらか一方、または両方を渡します。両方を渡した場合、アトミックではありません。最初にテキストが更新され、その後にステータスが更新されます。
• remove_items(list_id, item_ids) → boolean。

読み取り専用モードでは、すべての項目ツールが非表示になります。

カレンダー

• today() → {date, weekday, time, timezone} — お使いのマシンの現在の現地時刻です。すべてのツールの結果には、別の行としてこの値が末尾に追加されるため、アシスタントは自身の時計（多くの場合 UTC）ではなく、お使いの時計を基準に「明日」を判断できます。サーバーがお使いのコンピューター以外で動作している場合は、標準の TZ 環境変数（例：TZ=America/New_York）を設定してください。
• get_calendar(year, month) → [{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 は予定が発生する日です。end_day は複数日にわたる予定にのみ表示されます。Cozi は予定が重なるすべての月にその予定を表示するため、day が指定した月の範囲外になることがあります。繰り返し予定は、その月に Cozi が展開する日ごとに、発生ごとに1回ずつ表示されます。各項目にはシリーズの id、その発生日を示す day（発生が複数日にわたる場合は end_day も）、series_start、およびルールを示す Cozi の表記である recurrence が含まれます。Cozi アプリで削除された発生は除外され、skipped_days に記載されます。その月に発生が残っていないシリーズは、その月の一覧に表示されません。kind は誕生日などの予定以外の項目を示します。read_only 項目（祝日、登録済みカレンダーなど）は変更できず、その種別は source に記載されます。reminders は開始前の分数です。
• search_calendar(query) → {appointments: [...same fields, last_day?, next_days?], more?} — 月をまたいで Cozi 独自の検索を行います。繰り返しシリーズでは、直近の過去の発生と、その後の10件が報告されます。Cozi は数年前まで遡って検索します。新しく作成した予定が検索結果に表示されるまで数秒かかることがあります。
• create_appointment(subject, start, end, attendees?, all_day=false, notes='', location?, repeat?, reminders?, notify?) — start と end は ISO 日時（例：'2026-06-15T10:00:00'）です。終日予定（all_day=true）では日付のみ（例：'2026-06-15'）も指定でき、end に start と同じ日付を指定できます。時間指定の予定に日付のみを指定するとエラーになります。複数日にわたる予定では、end に後の日付を指定してください。結果では期間が end_day として報告されます。end が start より前の場合はエラーになります。repeat を指定するとシリーズになります。値は {frequency: 'daily'|'weekly'|'monthly'|'yearly', interval?, weekdays?, monthly_by?: 'day_of_month'|'weekday', until?} です（until を指定しない場合、繰り返しは無期限です）。reminders は開始前の分数です（例：[30, 1440]）。
• update_appointment(appointment_id, year, month, ...) — 取得してからマージする方式で部分更新します。(appointment_id, year, month) に加えて、変更するフィールドを指定してください。省略したフィールドは保持されます。時間指定の予定を終日予定に変更するには all_day=true を指定します。時間指定に変更するには、新しい start／end を指定します。end を指定すると、（新たに設定された可能性がある）開始日に基づいて予定の期間が再設定されるため、後の日付を指定すると複数日にわたる予定になり、開始日を指定すると1日に戻ります。start のみを指定すると、予定が移動し、長さは維持されます。予定が終日である場合、または終日に変更する場合は、start／end に日付のみを指定できます。時間指定の予定では日付のみを指定するとエラーになります。繰り返しシリーズには scope が必要です。'this' は occurrence_day に該当する発生のみを変更します（Cozi は変更後の予定を独立した予定として保存し、その予定が返されます）。'this_and_following' は該当する発生とそれ以降のすべてを変更します（Cozi はシリーズを分割します）。'series' はすべての発生を変更します。repeat はシリーズのルールを置き換えるか、単発の予定をシリーズに変更します。reminders は既存のリマインダーを置き換えます（[] を指定すると消去されます）。
• delete_appointment(appointment_id, year, month, scope?, occurrence_day?, notify?) → boolean。該当する id が (year, month) のページにない場合はエラーになります。繰り返しシリーズには scope が必要です。'this' は occurrence_day の発生を削除し、'this_and_following' はその発生の前でシリーズを終了し、'series' はすべての発生を削除します。単一の発生を削除した場合は、Cozi に反映されたことを確認するため、削除後に再取得します。 祝日、購読カレンダー、誕生日は、update_appointment と delete_appointment による操作が拒否されます。カレンダーへの書き込み時に notify=true を指定すると、通知を有効にしている参加者に Cozi の変更通知が送信されます（Cozi アプリの「通知」オプションと同様です）。デフォルトではオフです。

読み取り専用モードでは、create_appointment、update_appointment、delete_appointment は非表示になります。

ワークフローのヒント

特定の参加者を指定して予定を作成または更新する場合は、まず family_members() を呼び出し、その id 値を attendees 引数に使用してください。カレンダーツールは (year, month) ページの範囲で動作します。そのページの予定を更新または削除するときは、同じ year／month を渡してください。

v1（Python）からの移行

v2.0 は、以前の Python 実装を Node／TypeScript で書き直したもので、MCPB および npx として配布されています。ランタイムが変更されただけでなく、ツールの構成も統合されました。v1 用に作成したプロンプトがある場合は、次のように更新してください。

v1（Python、14 個のツール）	v2（Node、12 個のツール）
get_family_members	family_members
get_lists_by_type(t)	get_lists(list_type=t)
update_item_text(...) + mark_item(...)	update_item(text?, completed?)（統合）
add_item(list_id, item_text, ...)	add_item(list_id, text, ...)（パラメーター名を変更）
update_appointment(appointment_obj)	update_appointment(appointment_id, year, month, ...partial)
update_list（アイテムの並べ替え）	削除
delete_appointment(id)	delete_appointment(id, year, month)
get_lists は入れ子になったアイテムを返す	現在は概要のみを返す — アイテムは get_list_items(list_id) で取得

参考として、従来の v1 Python ソースは git タグ v1.0.0 に保存されています。

開発

Node 20 以上が必要です（.nvmrc を参照）。

nvm use
npm install
npm test               # vitest, mocked at the CoziClient boundary; no credentials
npm run test:live      # live conformance suite against real Cozi (creds.env); required before a release
npm run typecheck
npm run build          # tsup → dist/
npm run dev            # local stdio dev with COZI_USERNAME / COZI_PASSWORD env vars
npm run bundle:mcpb    # produces cozi-mcp.mcpb at repo root

リポジトリの構成：

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

Cozi HTTP クライアントは、別の npm パッケージとして公開するのではなく、src/cozi/ 内にインラインで配置されています。小規模で、この MCP サーバー以外では使い道がなく、別の依存関係を設けることによるサプライチェーン上のリスクも避けられるためです。ご自身のプロジェクト向けに Python 版をお探しの場合は、py-cozi-client をご覧ください。

謝辞

• Cozi 認証エンドポイントで ?apikey=coziwc|v…_production が必要であることは、Wetzel402/py-cozi PR #3 により、稼働中の my.cozi.com のウェブバンドルからリバースエンジニアリングされました。この発見がなければ、認証情報の有効性にかかわらず、サーバー環境からのログイン試行はすべて、誤解を招く 401 エラーで失敗します。
• Anthropic による Model Context Protocol とその TypeScript SDK を基盤としています。

商標および提携関係

Cozi および Cozi のロゴは Cozi Group Inc. の商標です。このプロジェクトは非公式のものであり、Cozi Group Inc. との提携、同社による承認、または同社の後援を受けていません。Cozi API の利用は自己責任であり、Cozi の利用規約が適用されます。

ライセンス

MIT — LICENSE をご覧ください。

コントリビューション

プルリクエストを歓迎します。提出前に npm test と npm run typecheck を実行してください。