Content
# carddav-mcp
<div align="center">
📇 A CardDAV Model Context Protocol (MCP) server to expose contacts and address books as tools for AI assistants.
[](https://github.com/dominik1001/carddav-mcp/actions/workflows/release.yml)
[](https://www.npmjs.com/package/carddav-mcp)
[](https://choosealicense.com/licenses/mit/)
[](https://modelcontextprotocol.io)
[](https://github.com/semantic-release/semantic-release)
</div>
## ✨ 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:
```bash
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:
1. Compile:
```bash
npx tsc
```
2. Run:
```bash
node dist/index.js
```
## Available Tools
<!-- TOOLS:START - generated by scripts/gen-tool-docs.ts -->
### 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`, and `phones`
### 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 optionally `org`, `title`, `note`) plus the raw vCard in `vcard`
### 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`: string
- `fn`: string — Formatted display name of the contact
- `name`: 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 / company
- `title`: string (optional) — Job title or role
- `note`: 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`: string
- `fn`: 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
<!-- TOOLS:END -->
## 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 via `claude -p` with a JSON output schema, validating that tool names, descriptions, schemas, and error messages are usable by an LLM.
## License
[MIT](https://choosealicense.com/licenses/mit/)
