carddav-mcp

A Model Context Protocol (MCP) server for CardDAV, the open contacts standard behind Nextcloud, Radicale, Baikal, SOGo, Fastmail, mailbox.org and iCloud.

Lets MCP clients like Claude Code, Claude Desktop or Codex work with your address book: find a person, read their card in full, add and correct contacts, keep groups, and fetch a contact photo — against your own server, with no vendor API in between.

Seventeen tools is the ceiling, not the floor: CARDDAV_ALLOW_TOOLS=essential registers a curated six instead, and a model picks the right tool far more reliably from six than from seventeen — see choosing which tools load.

What makes it different

A listing stays cheap on a real address book. list_contacts asks the server for a dozen named properties rather than for whole cards, which is the difference between a few kilobytes and several megabytes once inline photos are involved. The entries it returns say partial out loud, because a card retrieved that way is missing everything nobody asked for — and the write path refuses to build on one, re-fetching every time.

Both group conventions, read and written. vCard 4 defines KIND:group with MEMBER. Apple got there first and shipped X-ADDRESSBOOKSERVER-KIND on top of vCard 3, and that is what Apple Contacts, Nextcloud and most of the installed base actually store. This server reads both and writes whichever the address book already uses — a group written in the other convention is not a compatibility footnote, it is invisible in the client the person is looking at.

Writing reads first, and never rebuilds. A CardDAV PUT replaces the entire resource, so every change here is applied to the card as stored. The properties this server does not model — an X- property some phone wrote in 2014, a photo nobody mentioned — survive because they are never touched, not because anything preserves them. Every write carries the card's ETag, so a change somebody made in the meantime is reported instead of overwritten.

A birthday keeps the year it has, and no more. BDAY:--0415 means "the fifteenth of April, year unknown", which is what a phone writes when the year was never entered, and it is a large share of the real birthdays in any address book. Reported as {month, day} — not dropped for being incomplete, and not given an invented year.

Contacts are treated as somebody else's writing. An address book is rarely written only by its owner, and the attack that matters here does not run a tool: a card asserting that a bank's real number has changed needs the model to do nothing except believe it. Every string is fenced, datamarked and checked against named injection shapes — including one for exactly that.

Requirements

• Node.js 22 or newer, or Docker
• A CardDAV server and an account on it

Most hosted services want an app-specific password rather than the account password: Nextcloud, Fastmail and iCloud all issue one per application. Google Contacts is not supported — it requires OAuth and has deprecated password authentication for CardDAV.

Tested against Radicale and Baikal (sabre/dav) in CI on every pull request.

Configuration

¹ Either CARDDAV_USERNAME + CARDDAV_PASSWORD, or CARDDAV_TOKEN.

Booleans are compared against the literal string true where the switch lifts a protection (CARDDAV_INSECURE_TLS, CARDDAV_ALLOW_PLAINTEXT), and read tolerantly — 1, yes, TRUE — where it turns one on (CARDDAV_READ_ONLY). A typo should never quietly remove a guard.

The server starts without credentials on purpose, so a registry or a sandbox inspector can list its tools; every call then fails with setup instructions.

Choosing which tools load

Seventeen tools is a lot of context on every request, and a model picks worse from a long list than from a short one.

CARDDAV_ALLOW_TOOLS=essential                            # a curated six
CARDDAV_ALLOW_TOOLS=list_contacts,get_contact,create_contact
CARDDAV_ALLOW_TOOLS=list_*                               # one trailing * only
CARDDAV_DENY_TOOLS=delete_contact                        # subtracted from the above

essential selects list_address_books, list_contacts, get_contact, search_contacts, create_contact and update_contact — enough to find a person, read them, add one and correct one, with nothing irreversible in reach and the whole group surface left out.

Whatever is filtered out does not exist on the protocol rather than failing when called, and a name matching no tool stops the server at startup with the real names listed, instead of leaving a tool quietly missing.

Installation