cozi MCP

Cozi MCP服务器

非官方 模型上下文协议 服务器，让像克劳德这样的人工智能助手读取和更新您的 Cozi家庭组织者 列表和日历。

每个用户都针对自己的Cozi帐户运行自己的实例。您的凭据存储在MCP客户端的安全配置中（Claude Desktop的操作系统密钥链、Smithery的加密会话配置或您的本地环境），并且永远不会离开您的计算机——此服务器的作者无权访问您的数据。

安装

1.MCPB（建议用于Claude Desktop）

下载最新 .mcpb 从 发布页面 双击以在Claude Desktop中安装。系统会提示您输入Cozi用户名和密码——它们安全地存储在您的操作系统密钥链中。

此路径不需要在您的计算机上安装Node、npm或Python。

2.Smithery（适用于其他MCP客户）

对于Cursor、ChatGPT风格的客户端或连接到Smithery托管服务器的web代理：

在Smithery.ai上部署→

在Smithery UI中配置您的Cozi凭据；每个会话都使用自己的凭据集独立运行。

3.npx（适用于高级用户）

将此添加到您的Claude桌面 claude_desktop_config.json （或任何其他MCP客户端配置文件）：

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

需要节点20+。该软件包将在首次运行时下载。

信任与安全

Cozi没有OAuth-用户名/密码身份验证是API支持的唯一方式。此服务器诚实地处理了这一事实：

• 按用户，按架构。 每个用户都针对自己的Cozi帐户运行自己的实例。没有共享后端，没有代理，没有多租户数据库。此服务器的作者永远看不到任何人的凭据或数据。
• 凭据仅存在于MCP客户端的安全配置中。 Claude Desktop将它们存储在您的操作系统钥匙链中。Smithery对每个会话进行加密。npx路径从您自己设置的环境变量中读取它们。此服务器不会记录、写入磁盘或发送任何内容，除非 https://rest.cozi.com.
• API曲面受到约束。 此服务器仅联系 rest.cozi.com 对于Cozi web应用程序使用的相同端点（身份验证、列表、日历、家庭成员）。完整的请求/响应代码位于 src/cozi/ --你可以自己审核大约500行TypeScript。
• 开源，麻省理工学院授权。 固定特定版本(@mjucius/cozi-mcp@2.0.0)如果你想要一个稳定的目标，或者如果你想要零供应链信任，可以分叉仓库并运行自己的构建。

工具

服务器公开了12个工具。回报率很低 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?}].
• create_list(name, list_type) → {id, title, type}.
• delete_list(list_id) → boolean.

物品

• 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.

日历

• 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 和 end 是ISO日期时间（例如。 '2026-06-15T10:00:00').适用于全天活动 end 可能相等 start.
• update_appointment(appointment_id, year, month, ...) --通过fetch进行部分更新，然后合并：pass (appointment_id, year, month) 加上任何要更改的字段。省略的字段将被保留。将定时预约切换为全天通行证 all_day=true；切换到定时通过新 start/end.
• delete_appointment(appointment_id, year, month) → boolean.

工作流提示

在创建或更新与特定与会者的约会时，请致电 family_members() 首先，使用这些 id 值在 attendees arg。日历工具的范围为 (year, month) page--传递相同的内容 year/month 当从该页面更新或删除约会时返回。

从v1迁移（Python）

v2.0是对之前Python实现的Node/TypeScript重写，以MCPB/npx/Smithery的形式分发。运行时发生了变化，工具界面也得到了整合——如果你有针对v1编写的提示，请按如下方式更新它们：

旧版v1 Python源代码保留在git标签中 v1.0.0 以供参考。

发展

需要节点20+（请参见 .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

回购布局：

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

Cozi HTTP客户端内联在 src/cozi/ 而不是作为单独的npm包发布——它很小，只对这个MCP服务器有用，并避免了单独依赖的供应链表面区域。如果您希望在自己的项目中使用Python等效工具，请参阅 py cozi客户端.

致谢

• 这 ?apikey=coziwc|v…_production 对Cozi身份验证端点的要求是从现场反向工程的 my.cozi.com web捆绑包 Wetzel402/py cozi公关#3如果没有这一发现，无论凭证有效性如何，来自服务器环境的每次登录尝试都会以误导性的401失败。

商标和隶属关系

Cozi和Cozi标志是Cozi Group股份有限公司的商标。本项目为非官方项目，不隶属于Cozi Group股份有限公司，不由其背书或赞助。使用Cozi API的风险由您自行承担，并受 Cozi的服务条款.

许可证

麻省理工学院——见 许可证.

贡献

PR欢迎。请快跑 npm test 和 npm run typecheck 在提交之前。