Skip to main content
Glama

Cozi MCP Server

npm version License: MIT

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

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
  1. Run the server:

COZI_USERNAME=your@email.com COZI_PASSWORD=yourpass node dist/index.js
  1. 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

Support

Available Tools

9 tools
cozi_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

    A3.7/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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