ni-c/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
| Variable | Required | Description |
| ------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| CARDDAV_URL | yes | Root of the CardDAV server, e.g. https://dav.example.net. An address book collection URL works too and limits the server to that one book. |
| CARDDAV_USERNAME | yes¹ | Account name. |
| CARDDAV_PASSWORD | yes¹ | Password or app-specific password. Deleted from the environment once read. |
| CARDDAV_TOKEN | yes¹ | Bearer token instead of username and password. Not both. |
| CARDDAV_ADDRESSBOOKS | no | Comma-separated address books this server may touch, by path or final path segment. Default: every book the account can see. |