CardDAV address books
Read and write CardDAV contacts, groups and photos from an MCP client
- Pricing
- Open source
- Platforms
- CLI, self-hosted, macOS
- Runs
- Locally
- Version
- 0.1.4
- Listing updated
- 2 days ago
About CardDAV address books
CardDAV address books is an open-source MCP server for productivity. It runs locally on your machine and is started by your AI client.
Instead of a vendor API, this server talks straight to your own CardDAV server, the standard behind Nextcloud, Radicale, Baikal, SOGo, Fastmail, mailbox.org and iCloud. You paste a server root or a single address book URL and it finds the books behind it, reporting which vCard versions each one accepts. Google Contacts is not supported because it needs OAuth.
It registers up to seventeen tools, or a curated set of six with CARDDAV_ALLOW_TOOLS=essential, which the README argues helps a model pick the right one. Listings ask the server for a dozen named properties rather than whole cards, so inline photos do not bloat results, and entries are flagged as partial. Writes are applied to the card as stored and carry its ETag, so unmodelled properties survive and a concurrent change is reported rather than overwritten.
Safety is a focus. Destructive tools ask a person through MCP elicitation, or through a server-issued token where the client has no dialog. Contact text is fenced and checked for prompt-injection patterns, and CARDDAV_READ_ONLY=true leaves the write tools unregistered.
Install
Run in a terminal
claude mcp add carddav-mcp --env CARDDAV_URL='<CARDDAV_URL>' --env CARDDAV_PASSWORD='<CARDDAV_PASSWORD>' --env CARDDAV_TOKEN='<CARDDAV_TOKEN>' -- npx -y @ni-c/carddav-mcpAdd to claude_desktop_config.json
{
"mcpServers": {
"carddav-mcp": {
"command": "npx",
"args": [
"-y",
"@ni-c/carddav-mcp"
],
"env": {
"CARDDAV_URL": "<CARDDAV_URL>",
"CARDDAV_PASSWORD": "<CARDDAV_PASSWORD>",
"CARDDAV_TOKEN": "<CARDDAV_TOKEN>"
}
}
}
}Add to ~/.cursor/mcp.json
{
"mcpServers": {
"carddav-mcp": {
"command": "npx",
"args": [
"-y",
"@ni-c/carddav-mcp"
],
"env": {
"CARDDAV_URL": "<CARDDAV_URL>",
"CARDDAV_PASSWORD": "<CARDDAV_PASSWORD>",
"CARDDAV_TOKEN": "<CARDDAV_TOKEN>"
}
}
}
}Add to .vscode/mcp.json
{
"servers": {
"carddav-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@ni-c/carddav-mcp"
],
"env": {
"CARDDAV_URL": "<CARDDAV_URL>",
"CARDDAV_PASSWORD": "<CARDDAV_PASSWORD>",
"CARDDAV_TOKEN": "<CARDDAV_TOKEN>"
}
}
}
}Add to ~/.codeium/windsurf/mcp_config.json
{
"mcpServers": {
"carddav-mcp": {
"command": "npx",
"args": [
"-y",
"@ni-c/carddav-mcp"
],
"env": {
"CARDDAV_URL": "<CARDDAV_URL>",
"CARDDAV_PASSWORD": "<CARDDAV_PASSWORD>",
"CARDDAV_TOKEN": "<CARDDAV_TOKEN>"
}
}
}
}Add to your client's MCP settings (most use this shape)
{
"mcpServers": {
"carddav-mcp": {
"command": "npx",
"args": [
"-y",
"@ni-c/carddav-mcp"
],
"env": {
"CARDDAV_URL": "<CARDDAV_URL>",
"CARDDAV_PASSWORD": "<CARDDAV_PASSWORD>",
"CARDDAV_TOKEN": "<CARDDAV_TOKEN>"
}
}
}
}Configuration
CARDDAV_URLRoot of the CardDAV server, e.g. https://dav.example.net. An address book collection URL also works.RequiredCARDDAV_USERNAMEAccount name. Most hosted services want an app-specific password with it.CARDDAV_PASSWORDPassword or app-specific password. Deleted from the environment once read.CARDDAV_TOKENBearer token, as an alternative to username and password. Not both.CARDDAV_ADDRESSBOOKSComma-separated address books this server may touch, by path or final path segment. Default: all of them.CARDDAV_MAX_CONTACTSContacts a listing returns by default, 1 to 500 (default: 100)CARDDAV_READ_ONLYSet to true to register only the read tools (default: false)CARDDAV_INSECURE_TLSSet to true to accept a self-signed certificate on the configured host only (default: false)CARDDAV_ALLOW_PLAINTEXTSet to true to allow a plain http:// URL to a host that is not loopback, which sends the credentials and every contact unencrypted (default: false)CARDDAV_ALLOW_TOOLSComma-separated tool names or list_* prefixes to register; 'essential' selects a curated preset (default: all tools)CARDDAV_DENY_TOOLSComma-separated tool names or list_* prefixes to remove from whatever the allow list leftELICITATIONDeliberately unprefixed, and reaches every MCP server in the environment. Set to false to make guarded tools use the two-call token instead of a dialog (default: true)CARDDAV_URLRoot of the CardDAV server, e.g. https://dav.example.net. An address book collection URL also works.RequiredCARDDAV_USERNAMEAccount name. Most hosted services want an app-specific password with it.CARDDAV_PASSWORDPassword or app-specific password. Deleted from the environment once read.CARDDAV_TOKENBearer token, as an alternative to username and password. Not both.CARDDAV_ADDRESSBOOKSComma-separated address books this server may touch, by path or final path segment. Default: all of them.CARDDAV_MAX_CONTACTSContacts a listing returns by default, 1 to 500 (default: 100)CARDDAV_READ_ONLYSet to true to register only the read tools (default: false)CARDDAV_INSECURE_TLSSet to true to accept a self-signed certificate on the configured host only (default: false)CARDDAV_ALLOW_PLAINTEXTSet to true to allow a plain http:// URL to a host that is not loopback, which sends the credentials and every contact unencrypted (default: false)CARDDAV_ALLOW_TOOLSComma-separated tool names or list_* prefixes to register; 'essential' selects a curated preset (default: all tools)CARDDAV_DENY_TOOLSComma-separated tool names or list_* prefixes to remove from whatever the allow list leftELICITATIONDeliberately unprefixed, and reaches every MCP server in the environment. Set to false to make guarded tools use the two-call token instead of a dialog (default: true)
Tools this server provides (1)
Taken from the project documentation; the running server may differ.
- list_contacts
- Lists contacts using a small set of named properties and marks entries as partial
What it does
- Both group conventions
- Reads vCard 4 KIND:group and Apple's X-ADDRESSBOOKSERVER-KIND groups, and writes whichever the book already uses.
- Read-only mode
- CARDDAV_READ_ONLY=true registers only the read tools.
- Tool allow and deny lists
- CARDDAV_ALLOW_TOOLS and CARDDAV_DENY_TOOLS trim the tool set, including a curated essential preset.
- Safe writes
- Changes apply to the stored card with its ETag, so unknown properties are kept and conflicts are reported.
- Confirmation for deletes
- Destructive tools ask a person via MCP elicitation or a target-bound token.
- Partial birthdays
- A birthday without a year is reported as month and day instead of being dropped or given an invented year.
Good for
- Look up a colleague's full contact card from an AI assistant
- Add or correct contacts in a self-hosted Nextcloud or Radicale
- Manage contact groups without breaking how Apple Contacts shows them
- Fetch a contact photo
- Give an assistant read-only access to an address book
Pricing
Open source
Free to run; needs your own CardDAV server
Prices change. Check carddav-mcp.ni-c.de before you buy.
CardDAV address books FAQ
Which address book servers work?
Any CardDAV server; the README names Nextcloud, Radicale, Baikal, SOGo, Fastmail, mailbox.org and iCloud, and says it is tested against Radicale and Baikal in CI. Google Contacts is not supported.
What do I need to run it?
Node.js 24 or newer, or Docker, plus a CardDAV server and an account. Most hosted services want an app-specific password.
Can I stop it from changing contacts?
Yes. Set CARDDAV_READ_ONLY=true and only the read tools are registered.
Can I use it in a client that cannot launch local processes?
The site points to mcp-hub, a bridge that serves stdio MCP servers over Streamable HTTP behind an OAuth 2.1 login.
Is CardDAV address books free?
Yes. CardDAV address books is open source, so you can use and self-host it for free.
How do I add CardDAV address books to Claude Code?
Run this command in your terminal: claude mcp add carddav-mcp --env CARDDAV_URL='<CARDDAV_URL>' --env CARDDAV_PASSWORD='<CARDDAV_PASSWORD>' --env CARDDAV_TOKEN='<CARDDAV_TOKEN>' -- npx -y @ni-c/carddav-mcp
What are the best alternatives to CardDAV address books?
The closest alternatives to CardDAV address books are Ha MCP, Concord MCP, note1, CalderFlow and nicemails.
Alternatives to CardDAV address books

Ha MCP
MCP serverMCP server for managing and automating Home Assistant from AI assistants
Runs locally- 8 tools
- Open source
- 7.9K GitHub stars
- Productivity

Concord MCP
MCP serverLocal-first MCP server for messaging and shared work-state between coding agents
Runs locally- Freemium
- 1.3K GitHub stars
- Developer tools

note1
MCP serverMCP server giving AI assistants search and summaries across your note1 meetings
- 4 tools
- Remote
- Free trial
- 1 GitHub star
- Productivity

CalderFlow
MCP serverTurn notes or specs into editable flowcharts, timelines and funnels from an AI assistant
- 10 tools
- Remote
- Free
- Design and media

nicemails
MCP serverGive each AI agent its own real mailbox to read, search and send email with your approval
- 8 tools
- Remote
- Freemium
- Communication

ConvertAudioToText
MCP serverTranscribe audio and video links from Claude or ChatGPT and read the results
Not checked yet- 5 tools
- Remote
- Freemium
- Design and media