# Cozi MCP Server
An unofficial Model Context Protocol (MCP) server that provides AI assistants like Claude Desktop with access to [Cozi Family Organizer](https://www.cozi.com/) 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](https://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](https://smithery.ai/server/@mjucius/cozi_mcp)**
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:
```bash
git clone https://github.com/mjucius/cozi-mcp.git
cd cozi-mcp
```
2. Install dependencies:
```bash
uv sync
```
3. Start the development playground:
```bash
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:
```bash
# 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](https://smithery.ai/server/@mjucius/cozi_mcp), 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:
```bash
git clone https://github.com/yourusername/cozi-mcp.git
cd cozi-mcp
```
2. Install dependencies:
```bash
# With uv (recommended)
uv sync
# Or with pip
pip install -e .
```
3. Start the development playground:
```bash
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.
