cozi_mcp

🚀 Cozi MCP 服务器

这是一个非官方的模型上下文协议（MCP）服务器，它能让像 Claude Desktop 这样的人工智能助手访问 Cozi 家庭管理应用 的功能。该服务器通过标准化的 MCP 接口，将 Cozi 的列表、日历和家庭管理功能开放出来，这样你就可以让你的人工智能助手为你管理活动和列表。

🚀 现在可在 Smithery.ai 上部署 - 借助安全的凭证管理功能，将此 MCP 服务器部署到云端！

🚀 快速开始

你可以通过以下两种方式使用这个 MCP 服务器：

• 使用 Smithery.ai（推荐）：这是使用该 MCP 服务器最简单的方式。点击 在 Smithery.ai 上部署，访问服务器页面获取完整的安装说明，并可一键部署到你的人工智能助手中。
• 本地开发：适合想要修改或为项目做贡献的开发者。按照以下步骤操作：
  1. 克隆仓库：

  git clone https://github.com/mjucius/cozi-mcp.git
  cd cozi-mcp
  

  2. 安装依赖：

  uv sync
  

  3. 启动开发测试环境：

  uv run playground
  

✨ 主要特性

家庭管理

• 获取家庭成员及其信息

列表管理

• 查看所有列表（购物清单和待办事项列表）
• 按类型过滤列表
• 创建和删除列表

项目管理

• 向列表中添加项目
• 更新项目文本
• 将项目标记为已完成/未完成
• 从列表中移除项目

日历管理

• 查看任何月份的预约
• 创建新的预约
• 更新现有的预约
• 删除预约

📦 安装指南

使用 Smithery.ai（推荐）

通过 Smithery.ai 使用此 MCP 服务器是最简单的方法：

🚀 在 Smithery.ai 上部署

访问服务器页面获取完整的安装说明，并可一键部署到你的人工智能助手。

本地开发

对于想要修改或为项目做贡献的开发者：

1. 克隆仓库：

git clone https://github.com/mjucius/cozi-mcp.git
cd cozi-mcp

2. 安装依赖：

uv sync

3. 启动开发测试环境：

uv run playground

💻 使用示例

云端部署（Smithery.ai）

一旦在 Smithery.ai 上部署，你的 MCP 服务器将在云端运行，任何兼容 MCP 的人工智能助手都可以使用提供的端点 URL 访问它。

本地开发与测试

使用交互式测试环境在本地测试服务器：

# 启动交互式测试环境
uv run playground

# 或者启动开发服务器
uv run dev

测试环境提供了一个 Web 界面，用于测试所有 MCP 工具，并提供实时响应和调试信息。

与人工智能助手集成

将此 MCP 服务器集成到人工智能助手的最简单方法是通过 Smithery.ai 服务器页面，该页面为你的特定人工智能助手提供了详细的步骤说明。

对于进行本地开发的高级用户，可以使用标准输入输出接口在本地运行服务器。

📚 详细文档

开发要求

• Python 3.10 及以上版本
• Cozi 家庭管理应用账户
• uv（推荐）或 pip

依赖项

• mcp>=1.0.0 - 模型上下文协议框架
• py-cozi-client>=1.3.0 - Cozi API 客户端库
• smithery - Smithery.ai 部署框架

开发设置

1. 克隆仓库：

git clone https://github.com/yourusername/cozi-mcp.git
cd cozi-mcp

2. 安装依赖：

# 使用 uv（推荐）
uv sync

# 或者使用 pip
pip install -e .

3. 启动开发测试环境：

uv run playground

项目结构

cozi-mcp/
├── smithery.yaml              # Smithery.ai 部署配置
├── pyproject.toml             # 项目依赖和元数据  
├── src/
│   └── cozi_mcp/
│       ├── __init__.py       # 包导出
│       └── server.py         # MCP 服务器实现
└── [其他文件...]

可用的 MCP 工具

服务器为人工智能助手提供了以下工具：

家庭管理

• get_family_members - 获取账户中的所有家庭成员

列表管理

• get_lists - 获取所有列表（购物清单和待办事项列表）
• get_lists_by_type - 按类型（购物/待办）过滤列表
• create_list - 创建新列表
• delete_list - 删除现有列表

项目管理

• add_item - 向列表中添加项目
• update_item_text - 更新项目文本
• mark_item - 将项目标记为已完成/未完成
• remove_items - 从列表中移除项目

日历管理

• get_calendar - 获取特定月份的预约
• create_appointment - 创建新的日历预约
• update_appointment - 更新现有的预约
• delete_appointment - 删除预约

🔧 技术细节

这个 MCP 服务器使用以下技术构建：

• FastMCP - 简化的 MCP 服务器框架
• Smithery.ai - 云端部署和凭证管理
• py-cozi-client - Cozi API 的 Python 客户端库
• Pydantic 模型 - 所有 API 响应都使用结构化数据模型

服务器与 Cozi 保持单一的认证会话，并通过 MCP 协议开放所有功能。当部署在 Smithery.ai 上时，凭证将通过平台的配置系统进行安全管理。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

贡献说明

欢迎贡献代码！请随时提交拉取请求。