Cozi MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cozi MCP Server add milk, eggs, and bread to my shopping list"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-serverVia npx (No installation)
npx @brandcast_app/cozi-mcp-serverFrom Source
git clone https://github.com/BrandCast-Signage/cozi-mcp-server.git
cd cozi-mcp-server
npm install
npm run buildConfiguration
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 emailCOZI_PASSWORD(required): Your Cozi account passwordDEBUG(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 listscozi_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 abc123cozi_create_list
Create a new Cozi list.
Parameters:
title(string): The title of the new listtype(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 listItem Operations
cozi_add_item
Add a new item to a list.
Parameters:
listId(string): The list IDtext(string): The item text
Example:
User: Add "organic milk" to my shopping listcozi_edit_item
Edit an existing item's text.
Parameters:
listId(string): The list IDitemId(string): The item IDtext(string): The new text
Example:
User: Change "milk" to "whole milk" in my shopping listcozi_mark_item_complete
Mark an item as complete/done.
Parameters:
listId(string): The list IDitemId(string): The item ID
Example:
User: Mark "milk" as donecozi_mark_item_incomplete
Mark an item as incomplete/not done.
Parameters:
listId(string): The list IDitemId(string): The item ID
Example:
User: Uncheck "milk" from my listcozi_remove_item
Remove an item from a list permanently.
Parameters:
listId(string): The list IDitemId(string): The item ID
Example:
User: Remove "milk" from my shopping listUsage 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 buildWatch Mode
npm run watchTesting Locally
Build the project:
npm run buildRun the server:
COZI_USERNAME=your@email.com COZI_PASSWORD=yourpass node dist/index.jsThe 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-serverThen 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_USERNAMEandCOZI_PASSWORDare correctCheck 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
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
Available Tools
9 toolscozi_add_itemC
Add a new item to a Cozi list. The item will be added to the specified list.
Inputs: listId (required), text (required).
cozi_create_listC
Create a new Cozi list. Can be either a shopping list or a todo list.
Inputs: title (required), type (required).
cozi_delete_listA
Delete a Cozi list by ID. This permanently removes the list and all its items.
Inputs: listId (required).
cozi_edit_itemC
Edit the text of an existing item in a Cozi list.
Inputs: itemId (required), listId (required), text (required).
cozi_get_listB
Get a specific Cozi list by ID with all its items. Use this to see the full details of a single list.
Inputs: listId (required).
cozi_get_listsB
Get all Cozi lists (shopping and todo lists) with their items. Returns complete list of all lists including item counts and contents.
Inputs: no named parameters.
cozi_mark_item_completeC
Mark an item as complete/done in a Cozi list. This checks off the item.
Inputs: itemId (required), listId (required).
cozi_mark_item_incompleteA
Mark an item as incomplete/not done in a Cozi list. This unchecks the item.
Inputs: itemId (required), listId (required).
cozi_remove_itemA
Remove/delete an item from a Cozi list. This permanently deletes the item.
Inputs: itemId (required), listId (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 9 tools
Every tool has a clearly distinct purpose targeting specific resources and actions: adding/editing/removing items, creating/deleting/getting lists, and marking items complete/incomplete. No ambiguity exists between tools like cozi_add_item and cozi_edit_item, which handle different lifecycle stages.
All tools follow a perfect verb_noun pattern with the 'cozi_' prefix, using consistent snake_case throughout. The naming convention is predictable and readable, with verbs like add, create, delete, edit, get, mark, and remove consistently applied to nouns like item and list.
With 9 tools, the server is well-scoped for managing Cozi lists and items. Each tool earns its place by covering essential operations without bloat, providing a balanced set for CRUD and lifecycle management in this domain.
The toolset offers complete CRUD/lifecycle coverage for lists (create, get, delete) and items (add, edit, remove, mark complete/incomplete). No gaps exist; agents can fully manage lists and items from creation to deletion without dead ends.
Related MCP Connectors
Manage your family's calendars and lists in Cozi. View, create, and update appointments; organizeβ¦
Read and edit your Kori grocery lists: add, check off, edit and remove items.
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
To-do lists by voice or chat: add tasks with due dates, check them off, see what's due.