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)

npm install -g @brandcast_app/cozi-mcp-server

Via npx (No installation)

npx @brandcast_app/cozi-mcp-server

From Source

git clone https://github.com/BrandCast-Signage/cozi-mcp-server.git
cd cozi-mcp-server
npm install
npm run build

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

{
  "mcpServers": {
    "cozi": {
      "command": "npx",
      "args": ["-y", "@brandcast_app/cozi-mcp-server"],
      "env": {
        "COZI_USERNAME": "your@email.com",
        "COZI_PASSWORD": "your-password"
      }
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "cozi": {
      "command": "cozi-mcp-server",
      "env": {
        "COZI_USERNAME": "your@email.com",
        "COZI_PASSWORD": "your-password"
      }
    }
  }
}

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:

User: Show me all my Cozi lists

cozi_get_list

Get a specific list by ID with all its items.

Parameters:

• listId (string): The ID of the list

Example:

User: Show me the details of list abc123

cozi_create_list

Create a new Cozi list.

Parameters:

• title (string): The title of the new list
• type (string): Either "shopping" or "todo"

Example:

User: Create a new shopping list called "Costco Run"

cozi_delete_list

Delete a list permanently.

Parameters:

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

Example:

User: Delete the Costco Run list

Item Operations

cozi_add_item

Add a new item to a list.

Parameters:

• listId (string): The list ID
• text (string): The item text

Example:

User: Add "organic milk" to my shopping list

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:

User: Change "milk" to "whole milk" in my shopping list

cozi_mark_item_complete

Mark an item as complete/done.

Parameters:

• listId (string): The list ID
• itemId (string): The item ID

Example:

User: Mark "milk" as done

cozi_mark_item_incomplete

Mark an item as incomplete/not done.

Parameters:

• listId (string): The list ID
• itemId (string): The item ID

Example:

User: Uncheck "milk" from my list

cozi_remove_item

Remove an item from a list permanently.

Parameters:

• listId (string): The list ID
• itemId (string): The item ID

Example:

User: Remove "milk" from my shopping list

Usage Examples

With Claude Desktop

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

View Lists:

You: What's on my shopping list?
Claude: [Uses cozi_get_lists to fetch and display your lists]

Add Items:

You: Add bananas, apples, and bread to my shopping list
Claude: [Uses cozi_add_item for each item]

Manage Tasks:

You: I finished buying milk, mark it as done
Claude: [Uses cozi_mark_item_complete]

Create Lists:

You: Create a new todo list for weekend chores
Claude: [Uses cozi_create_list]

Development

Building

npm run build

Watch Mode

npm run watch

Testing Locally

1. Build the project:

npm run build

2. Run the server:

COZI_USERNAME=your@email.com COZI_PASSWORD=yourpass node dist/index.js

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

Testing with MCP Inspector

npx @modelcontextprotocol/inspector npx -y @brandcast_app/cozi-mcp-server

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