@miguelarios/card-mcp

MCP server for contacts via CardDAV — CRUD contacts, contact groups, search, resolve names to emails, and manage address books.

Protocol support

Speaks MCP revision 2026-07-28 over stdio or Streamable HTTP, and still serves 2025-era clients from the same tool definitions. Every tool declares a title, all four behaviour annotations, and an outputSchema, and returns validated structuredContent.

delete_contact, delete_group and delete_address_book ask the user to confirm before deleting. Set PIM_MCP_CONFIRM=off to skip confirmation in headless use.

Requires Node.js 22.12.0 or newer.

Usage

npx @miguelarios/card-mcp

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CARDDAV_URL | Yes | CardDAV server URL | | CARDDAV_USER | Yes | CardDAV username | | CARDDAV_PASS | Yes | CardDAV password | | CARDDAV_SERVER_SEARCH | No | Set to off to never search or look up contacts with a filtered addressbook-query REPORT and always fetch the whole book instead. A server that rejects the REPORT is fallen back from automatically; this is for one whose filter matching is wrong. |

Over HTTP and in Docker

Set PIM_MCP_TRANSPORT=http to serve Streamable HTTP at /mcp instead of stdio — for a client that connects by URL, or a server in a container. PIM_MCP_HTTP_HOST (default 127.0.0.1) and PIM_MCP_HTTP_PORT (default 3000) set where it listens, and GET /healthz answers ok for health checks. The HTTP server does no authentication: keep it on loopback or a private network, and put an OAuth proxy in front before exposing it further.

docker run -d --name card-mcp --restart unless-stopped --user node \
  --env-file card.env \
  -e PIM_MCP_TRANSPORT=http -e PIM_MCP_HTTP_HOST=0.0.0.0 \
  -p 127.0.0.1:3003:3000 -v card-mcp-home:/home/node \
  node:22-alpine npx -y @miguelarios/[email protected]

See the Docker guide for the env file, stdio use from a desktop client, Docker Compose, and exposing a server safely, and the README for every HTTP setting.

Tools (17)

See docs/tools/card-mcp.md for full parameter and output details.

| Tool | Description | |------|-------------| | list_contacts | List and search contacts by name, email, phone, org (groups hidden unless includeGroups) | | get_contact | Get full contact details by UID | | create_contact | Create a new contact | | update_contact | Update an existing contact (merge-based; null clears a field) | | delete_contact | Delete a contact by UID | | resolve_contact | Given a name, return email address | | move_contacts | Move contacts to another address book (keeps each UID) | | copy_contacts | Copy contacts into another address book (each copy gets a new UID) | | list_groups | List contact groups with member counts | | get_group | Get a group with its members resolved to contacts | | create_group | Create a contact group from member UIDs | | update_group | Rename a group, add and remove members | | delete_group | Delete a group, keeping its members (confirms first) | | list_address_books | List address books with metadata and opt-in contact counts | | create_address_book | Create an address book (extended MKCOL) | | rename_address_book | Rename an address book or update its description | | delete_address_book | Delete an address book and its contacts (confirms first) |

Every addressBook parameter takes a display name (e.g. Work) as well as a URL. When it is omitted, reads and lookups by UID cover every address book in the account, and each returned contact carries an addressBook label to pass back; create_contact and create_group default to the first book.

Contact groups are vCards with KIND:group (written in the vCard 3.0 X-ADDRESSBOOKSERVER-KIND form that Apple, iCloud and SabreDAV-based servers such as Nextcloud read). A group's members must be contacts in the same address book.

License

MIT