Cozi MCP Server

Model Context Protocol (MCP) server for Cozi Family Organizer. Enables Claude and other MCP clients to manage shopping lists and todo lists through the Cozi API.

⚠️ Important Disclaimer

This is an UNOFFICIAL MCP server. Cozi does not provide a public API. This implementation uses the unofficial @brandcast_app/cozi-api-client which is based on reverse engineering.

Use at your own risk:

• The API may change without notice

• Your Cozi account could be suspended for using unofficial clients

• This server is provided AS-IS with no warranties

• Not affiliated with or endorsed by Cozi

Features

• 📝 List Management: Create, read, and delete shopping/todo lists

• ✅ Item Operations: Add, edit, complete, and remove items

• 🔄 Real-time Sync: Changes are immediately reflected in Cozi

• 🤖 Claude Integration: Use natural language to manage your Cozi lists

• 🔐 Secure: Credentials stored in environment variables

Installation

Via npm (Recommended)

Via npx (No installation)

From Source

Configuration

Claude Desktop

Add to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Or if installed globally:

Environment Variables

• COZI_USERNAME (required): Your Cozi account email

• COZI_PASSWORD (required): Your Cozi account password

• DEBUG (optional): Set to "true" to enable debug logging

Available Tools

The server exposes the following MCP tools:

List Operations

cozi_get_lists

Get all Cozi lists (shopping and todo) with their items.

Returns: Array of lists with items

Example:

cozi_get_list

Get a specific list by ID with all its items.

Parameters:

• listId (string): The ID of the list

Example:

cozi_create_list

Create a new Cozi list.

Parameters:

• title (string): The title of the new list

• type (string): Either "shopping" or "todo"

Example:

cozi_delete_list

Delete a list permanently.

Parameters:

• listId (string): The ID of the list to delete

Example:

Item Operations

cozi_add_item

Add a new item to a list.

Parameters:

• listId (string): The list ID

• text (string): The item text

Example:

cozi_edit_item

Edit an existing item's text.

Parameters:

• listId (string): The list ID

• itemId (string): The item ID

• text (string): The new text

Example:

cozi_mark_item_complete

Mark an item as complete/done.

Parameters:

• listId (string): The list ID

• itemId (string): The item ID

Example:

cozi_mark_item_incomplete

Mark an item as incomplete/not done.

Parameters:

• listId (string): The list ID

• itemId (string): The item ID

Example:

cozi_remove_item

Remove an item from a list permanently.

Parameters:

• listId (string): The list ID

• itemId (string): The item ID

Example:

Usage Examples

With Claude Desktop

Once configured, you can interact with Cozi through natural language:

View Lists:

Add Items:

Manage Tasks:

Create Lists:

Development

Building

Watch Mode

Testing Locally

1. Build the project:

2. Run the server:

3. The server will start and wait for MCP protocol messages on stdin/stdout

Testing with MCP Inspector

Then set environment variables in the inspector UI.

API Client

This server is built on top of @brandcast_app/cozi-api-client. If you need direct API access without MCP, use the client library directly.

Troubleshooting

Authentication Fails

• Verify COZI_USERNAME and COZI_PASSWORD are correct

• Check that your Cozi account is active

• Try logging in to the Cozi website to verify credentials

Server Not Starting

• Ensure Node.js >= 18.0.0 is installed

• Check that environment variables are properly set

• Enable debug mode: DEBUG=true

Tools Not Appearing in Claude

• Restart Claude Desktop after configuration changes

• Check config file syntax (valid JSON)

• Verify the server path/command is correct

Security Notes

• Store credentials securely in environment variables

• Never commit credentials to version control

• Consider using a dedicated Cozi account for automation

• The server runs locally and does not send data anywhere except to Cozi

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT License - see LICENSE file for details.

Credits

• Built with the Model Context Protocol SDK

• Uses @brandcast_app/cozi-api-client

• Based on reverse engineering from py-cozi

Related Projects

• cozi-api-client - The underlying API client

• Model Context Protocol - Learn more about MCP

Support

• 🐛 Report Issues

• 💬 Discussions

• 📖 MCP Documentation