Cozi MCP Server

An unofficial Model Context Protocol (MCP) server that provides AI assistants like Claude Desktop with access to Cozi Family Organizer functionality. This server exposes Cozi's lists, calendar, and family management features through a standardized MCP interface so you can ask your AI to manage events and lists for you.

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

Features

Family Management

• Get 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 easiest way to use this MCP server is through Smithery.ai:

🚀 Deploy on Smithery.ai

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

Local Development

For developers who want 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

Cloud Deployment (Smithery.ai)

Once deployed on Smithery.ai, your MCP server runs 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 provides 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.

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 - Get all family members in the account

List Management

• get_lists - Get 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 - Get appointments for a specific month
• create_appointment - Create new calendar appointments
• update_appointment - Update existing appointments
• delete_appointment - Delete appointments

Architecture

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

MIT License - see LICENSE file for details.

Contributing

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