Cozi MCP

🚀 Cozi MCP Server

An unofficial Model Context Protocol (MCP) server that enables AI assistants like Claude Desktop to access the functionality of Cozi Family Organizer. This server exposes Cozi's lists, calendar, and family management features via a standardized MCP interface, allowing you to ask your AI to manage events and lists on your behalf.

🚀 Now deployable on Smithery.ai - Deploy this MCP server to the cloud with secure credential management!

🚀 Quick Start

This MCP server offers seamless integration with AI assistants, enabling them to access Cozi Family Organizer's features. You can deploy it on Smithery.ai or set it up for local development.

✨ Features

Family Management

• Retrieve family members and their information.

List Management

• View all lists (shopping and todo lists).
• Filter lists by type.
• Create and delete lists.

Item Management

• Add items to lists.
• Update item text.
• Mark items as complete/incomplete.
• Remove items from lists.

Calendar Management

• View appointments for any month.
• Create new appointments.
• Update existing appointments.
• Delete appointments.

📦 Installation

Using Smithery.ai (Recommended)

The simplest way to use this MCP server is through Smithery.ai:

🚀 Deploy on Smithery.ai

Visit the server page for comprehensive installation instructions and one-click deployment to your AI assistant.

Local Development

For developers looking to modify or contribute to the project:

1. Clone the repository:

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

2. Install dependencies:

uv sync

3. Start the development playground:

uv run playground

💻 Usage Examples

Cloud Deployment (Smithery.ai)

Once deployed on Smithery.ai, your MCP server operates in the cloud and can be accessed by any MCP-compatible AI assistant using the provided endpoint URL.

Local Development & Testing

Test the server locally with the interactive playground:

# Start the interactive playground
uv run playground

# Or start development server
uv run dev

The playground offers a web interface to test all MCP tools with real-time responses and debugging information.

Integration with AI Assistants

The easiest way to integrate this MCP server is through the Smithery.ai server page, which provides step-by-step instructions for your specific AI assistant.

For advanced users doing local development, the server can be run locally using the stdio interface.

📚 Documentation

Development Requirements

• Python 3.10+
• Cozi Family Organizer account
• uv (recommended) or pip

Dependencies

• mcp>=1.0.0 - Model Context Protocol framework
• py-cozi-client>=1.3.0 - Cozi API client library
• smithery - Smithery.ai deployment framework

Development Setup

1. Clone the repository:

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

2. Install dependencies:

# With uv (recommended)
uv sync

# Or with pip
pip install -e .

3. Start the development playground:

uv run playground

Project Structure

cozi-mcp/
├── smithery.yaml              # Smithery.ai deployment config
├── pyproject.toml             # Project dependencies and metadata  
├── src/
│   └── cozi_mcp/
│       ├── __init__.py       # Package exports
│       └── server.py         # MCP server implementation
└── [other files...]

Available MCP Tools

The server exposes these tools for AI assistants:

Family Management

• get_family_members - Retrieve all family members in the account.

List Management

• get_lists - Retrieve all lists (shopping and todo).
• get_lists_by_type - Filter lists by type (shopping/todo).
• create_list - Create new lists.
• delete_list - Delete existing lists.

Item Management

• add_item - Add items to lists.
• update_item_text - Update item text.
• mark_item - Mark items complete/incomplete.
• remove_items - Remove items from lists.

Calendar Management

• get_calendar - Retrieve appointments for a specific month.
• create_appointment - Create new calendar appointments.
• update_appointment - Update existing appointments.
• delete_appointment - Delete appointments.

🔧 Technical Details

This MCP server is built using:

• FastMCP - Simplified MCP server framework
• Smithery.ai - Cloud deployment and credential management
• py-cozi-client - Python client library for Cozi's API
• Pydantic models - All API responses use structured data models

The server maintains a single authenticated session with Cozi and exposes all functionality through the MCP protocol. When deployed on Smithery.ai, credentials are securely managed through the platform's configuration system.

📄 License

This project is under the MIT License. See the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.