
carddav-mcp
io.github.langmail/carddav-mcp
CardDAV contacts as MCP tools: list address books; list, get, create, update and delete contacts.
Documentation
carddav-mcp
š A CardDAV Model Context Protocol (MCP) server to expose contacts and address books as tools for AI assistants.
Maintained by the team behind Langmail. Want mail, calendar and contacts for your agent over one hosted MCP, with OAuth and nothing to run? ā langmail.me
⨠Features
- Connect to CardDAV servers
- List address books
- List contacts in an address book
- Get the full details of a single contact
- Create contacts (vCard)
- Update contacts ā partial updates that preserve vCard properties written by other clients
- Delete contacts by UID
Setup
{
"mcpServers": {
...,
"contacts": {
"command": "npx",
"args": [
"carddav-mcp"
],
"env": {
"CARDDAV_BASE_URL": "<CardDAV server URL>",
"CARDDAV_USERNAME": "<CardDAV username>",
"CARDDAV_PASSWORD": "<CardDAV password>"
}
}
}
}
Development
Quick Start
Run the MCP server in development mode with auto-reload:
npm run dev
This will run the TypeScript code directly with watch mode and automatically load environment variables from .env.
Manual Build
Alternatively, you can compile TypeScript to JavaScript and run it:
- Compile:
npx tsc
- Run:
node dist/index.js
Available Tools
list-address-books
List all address books returning both name and URL
Parameters: none
Returns:
- List of all available address books
list-contacts
List all contacts in the address book specified by its URL. Returns a summary per contact; use get-contact for full details.
Parameters:
addressBookUrl: string
Returns:
- A list of contacts, each containing
uid,fn(formatted name),emails, andphones
get-contact
Get the full details of a single contact in the address book specified by its URL
Parameters:
uid: string ā Unique identifier of the contact to fetch (obtained from list-contacts)addressBookUrl: string
Returns:
- The contact's parsed fields (
uid,fn,name,emails,phones, and optionallyorg,title,note) plus the raw vCard invcard
create-contact
Creates a contact (vCard) in the address book specified by its URL. If name is omitted, structured name parts are derived from fn.
Parameters:
addressBookUrl: stringfn: string ā Formatted display name of the contactname: object (optional) ā Structured name parts (family, given, middle, ...)family: string (optional)given: string (optional)middle: string (optional)prefix: string (optional)suffix: string (optional)
emails: array of string (optional)phones: array of string (optional)org: string (optional) ā Organization / companytitle: string (optional) ā Job title or rolenote: string (optional)
Returns:
- The unique ID of the created contact
update-contact
Updates an existing contact in the address book specified by its URL. Only provided fields are changed; emails and phones replace the full list (pass an empty array to clear them, or an empty string to clear org, title, or note). Other vCard properties are preserved.
Parameters:
uid: string ā Unique identifier of the contact to update (obtained from list-contacts)addressBookUrl: stringfn: string (optional)name: object (optional)family: string (optional)given: string (optional)middle: string (optional)prefix: string (optional)suffix: string (optional)
emails: array of string (optional)phones: array of string (optional)org: string (optional)title: string (optional)note: string (optional)
Returns:
- The unique ID of the updated contact
delete-contact
Deletes a contact in the address book specified by its URL
Parameters:
uid: string ā Unique identifier of the contact to delete (obtained from list-contacts)addressBookUrl: string
Returns:
- Confirmation message when the contact is successfully deleted
Smoke Tests
Two complementary end-to-end checks against a real CardDAV server (both read credentials from .env):
npm run smokeā deterministic SDK harness (scripts/smoke.ts). Spawns the built server over stdio via the MCP client SDK and asserts the create ā list ā get ā update ā delete contact round-trip.npm run smoke:agentā agent-ergonomics harness (scripts/smoke-agent.sh). Drives the server viaclaude -pwith a JSON output schema, validating that tool names, descriptions, schemas, and error messages are usable by an LLM.
License
carddav-mcpnpm install carddav-mcpRelated Servers
io.github.langmail/caldav-mcp
CalDAV calendar operations (list, create, update, delete events) as MCP tools.
io.github.langmail/imap-mcp
IMAP email as MCP tools: create draft messages in the Drafts folder of any IMAP mailbox.
io.github.langmail/langmail-mcp
Self-hosted MCP server for Stalwart: email, calendar and contacts over JMAP, CalDAV and CardDAV.