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 文件。

貢獻說明

歡迎貢獻代碼！請隨時提交拉取請求。