Cozi MCP Server

# Cozi MCP Server [](https://badge.fury.io/js/%40brandcast_app%2Fcozi-mcp-server) [](https://opensource.org/licenses/MIT) Model Context Protocol (MCP) server for [Cozi Family Organizer](https://www.cozi.com/). 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](https://www.npmjs.com/package/@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) ```bash npm install -g @brandcast_app/cozi-mcp-server ``` ### Via npx (No installation) ```bash npx @brandcast_app/cozi-mcp-server ``` ### From Source ```bash 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` ```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: ```json { "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 ```bash npm run build ``` ### Watch Mode ```bash npm run watch ``` ### Testing Locally 1. Build the project: ```bash npm run build ``` 2. Run the server: ```bash 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 ```bash 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](https://www.npmjs.com/package/@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](CONTRIBUTING.md) for guidelines. ## License MIT License - see [LICENSE](LICENSE) file for details. ## Credits - Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol) - Uses [@brandcast_app/cozi-api-client](https://www.npmjs.com/package/@brandcast_app/cozi-api-client) - Based on reverse engineering from [py-cozi](https://github.com/Wetzel402/py-cozi) ## Related Projects - [cozi-api-client](https://github.com/BrandCast-Signage/cozi-api-client) - The underlying API client - [Model Context Protocol](https://modelcontextprotocol.io) - Learn more about MCP ## Support - 🐛 [Report Issues](https://github.com/BrandCast-Signage/cozi-mcp-server/issues) - 💬 [Discussions](https://github.com/BrandCast-Signage/cozi-mcp-server/discussions) - 📖 [MCP Documentation](https://modelcontextprotocol.io/docs)