cozi-mcp-server by BrandCast-Signage - MCP Server

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

Build the project:

npm run build

Run the server:

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

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 for guidelines.

License

MIT License - see 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