carddav-mcp

# carddav-mcp

<!-- badges: start -->

[![CI](https://img.shields.io/github/actions/workflow/status/ni-c/carddav-mcp/ci.yml?branch=main&label=CI)](https://github.com/ni-c/carddav-mcp/actions/workflows/ci.yml)
[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/ni-c/carddav-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/ni-c/carddav-mcp)
<a href="https://socket.dev/npm/package/@ni-c/carddav-mcp"><img src="https://socket.dev/api/badge/npm/package/@ni-c/carddav-mcp" alt="Socket supply-chain report" height="20"></a>
[![Glama score](https://glama.ai/mcp/servers/ni-c/carddav-mcp/badges/score.svg)](https://glama.ai/mcp/servers/ni-c/carddav-mcp)
<br>
[![npm version](https://img.shields.io/npm/v/%40ni-c%2Fcarddav-mcp)](https://www.npmjs.com/package/@ni-c/carddav-mcp)
[![container image](https://img.shields.io/badge/ghcr.io-ni--c%2Fcarddav--mcp-4f46e5?logo=docker&logoColor=white)](https://github.com/ni-c/carddav-mcp/pkgs/container/carddav-mcp)
[![HTTP via mcp-hub](https://img.shields.io/badge/HTTP-via%20mcp--hub-4f46e5?logo=modelcontextprotocol&logoColor=white)](https://mcp-hub.ni-c.de)
<br>
[![docs](https://img.shields.io/badge/docs-carddav--mcp.ni--c.de-4f46e5?logo=readthedocs&logoColor=white)](https://carddav-mcp.ni-c.de)
[![sponsor](https://img.shields.io/badge/sponsor-ni--c-ea4aaa?logo=githubsponsors&logoColor=white)](https://github.com/sponsors/ni-c)
<!-- badges: end -->

A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server for
[CardDAV](https://datatracker.ietf.org/doc/html/rfc6352), 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](#choosing-which-tools-load).

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://carddav-mcp.ni-c.de/architecture-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="https://carddav-mcp.ni-c.de/architecture-light.svg">
  <img alt="An MCP client speaks stdio to carddav-mcp, which speaks WebDAV over HTTPS to a CardDAV server. Answers come back marked as untrusted contact content." src="https://carddav-mcp.ni-c.de/architecture.svg">
</picture>

![Three tool calls against a local Radicale: listing the contacts in an address book, finding one by name, and reading a group with its member count.](https://carddav-mcp.ni-c.de/demo.gif)

## 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.                                                           |
| `CARDDAV_MAX_CONTACTS`    | no       | Contacts a listing returns by default, 1–500. Default `100`.                                                                                                                           |
| `CARDDAV_READ_ONLY`       | no       | `true` registers only the read tools. Default `false`.                                                                                                                                 |
| `CARDDAV_INSECURE_TLS`    | no       | `true` accepts a self-signed certificate **on the configured host only** — and switches off hostname verification with it. Default `false`.                                            |
| `CARDDAV_ALLOW_PLAINTEXT` | no       | `true` allows a plain `http://` URL to a host that is not loopback, which sends the credentials and every contact unencrypted. Otherwise such a URL refuses to start. Default `false`. |
| `CARDDAV_ALLOW_TOOLS`     | no       | Tool names, a prefix with one trailing `*`, or `essential`.                                                                                                                            |
| `CARDDAV_DENY_TOOLS`      | no       | Subtracted from whatever the allow list left.                                                                                                                                          |
| `ELICITATION`             | no       | **Not prefixed** — one export reaches every MCP server in the environment. `false` makes guarded tools use the two-call token instead of a dialog. Default `true`.                     |

¹ 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.

```sh
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

### Claude Cod