contacts-mcp

An MCP server that gives AI assistants full contact management capabilities — create, search, deduplicate, merge, sync across systems, and roll back any change with confidence.

Contacts are stored as individual vCard files in a git repository. Every mutation is a git commit, so you get full version history, diffs, and revert for free. The AI can make sweeping changes knowing everything is recoverable.

Quick Start

Prerequisites

• Bun 1.0+

• Git (available in PATH)

Install & Build

cd contacts-mcp
bun install
bun run build

Add to Claude Code

claude mcp add contacts bun /path/to/contacts-mcp/dist/index.js

Add to Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contacts": {
      "command": "bun",
      "args": ["/path/to/contacts-mcp/dist/index.js"]
    }
  }
}

Development Mode

Run directly from source without building (bun runs TypeScript natively):

bun run dev

Verify It Works

Use the MCP Inspector to test interactively:

bunx @modelcontextprotocol/inspector bun dist/index.js

Related MCP server: veyra-contacts

What It Does

Once connected, your AI assistant gets 14 tools and 4 resources for managing contacts:

Tools

CLI Export And Resolve

The binary still starts the MCP stdio server by default. It also supports deterministic non-AI command-line operations for other local tools:

contacts-mcp export --format json --output contacts.json
contacts-mcp export --format json --output -
contacts-mcp resolve --input contact-points.json --output -
contacts-mcp sync-provider --provider apple --direction pull

resolve input is JSON:

{
  "phones": ["+18016022838", "(801) 602-2838"],
  "emails": ["alex@example.com"],
  "defaultCountry": "US"
}

Use CONTACTS_MCP_STORE=/path/to/store when exporting or resolving against a custom store path.

Before exporting Contacts from macOS, pull Apple Contacts into the local git-backed store:

contacts-mcp sync-provider --provider apple --direction pull

If you do not have an Apple provider in ~/.contacts-mcp/config.json, the CLI will use the built-in Apple provider on macOS. The first run may trigger a Contacts permission prompt.

Resources

How Storage Works

~/.contacts-mcp/store/
├── .git/                    # Git repository
├── contacts/
│   ├── <uuid>.vcf          # One vCard 4.0 file per contact
│   └── ...
├── archive/
│   └── <uuid>.vcf          # Soft-deleted contacts
└── .metadata/
    ├── providers.json       # Provider config & sync state
    └── merge-log.json       # Audit trail for merges

• One file per contact — each contact is a standard vCard 4.0 (.vcf) file named by its UUID.

• Every change is a commit — creating, updating, deleting, merging, importing all produce descriptive git commits like Create contact: Jane Smith (uuid) or Merge contacts: Jane + J. Smith -> Jane Smith.

• Soft deletes — delete_contact moves the file from contacts/ to archive/. It's still in the repo and can be found by get_contact or restored via rollback.

• Bulk operations get tags — imports and syncs create pre-import-<timestamp> / post-import-<timestamp> git tags so you can roll back an entire bulk operation in one shot.

• Rollback = git revert — always creates new commits (never reset --hard), so the full audit trail is preserved and rollbacks are themselves reversible.

Configuration

Configuration is loaded from ~/.contacts-mcp/config.json (or the path in CONTACTS_MCP_CONFIG env var).

Minimal Config (Local Only)

No config file needed. The server works out of the box with the local git store at ~/.contacts-mcp/store/.

Custom Store Path

{
  "storePath": "/path/to/my/contacts-repo"
}

Or via environment variable:

CONTACTS_MCP_STORE=/path/to/my/contacts-repo bun dist/index.js

Full Config with Providers

{
  "storePath": "~/.contacts-mcp/store",
  "providers": [
    {
      "name": "google-personal",
      "type": "google",
      "enabled": true,
      "config": {
        "clientId": "your-client-id.apps.googleusercontent.com",
        "clientSecret": "your-client-secret",
        "refreshToken": "your-refresh-token"
      }
    },
    {
      "name": "fastmail",
      "type": "carddav",
      "enabled": true,
      "config": {
        "serverUrl": "https://carddav.fastmail.com/dav/addressbooks",
        "username": "you@fastmail.com",
        "password": "app-specific-password",
        "authMethod": "Basic"
      }
    },
    {
      "name": "apple",
      "type": "apple",
      "enabled": true,
      "config": {}
    }
  ]
}

Environment Variables

Provider Setup

Google Contacts

Uses the Google People API. You need OAuth2 credentials:

1. Go to Google Cloud Console and create a project.

2. Enable the People API.

3. Create OAuth2 credentials (Desktop app type).

4. Use the OAuth2 playground or a script to get a refresh token with https://www.googleapis.com/auth/contacts scope.

5. Add clientId, clientSecret, and refreshToken to your config.

Apple Contacts (macOS only)

Uses JavaScript for Automation (JXA) via osascript. No credentials needed, but:

1. The first time you sync, macOS will prompt you to allow terminal/IDE access to Contacts.

2. Grant permission in System Settings > Privacy & Security > Contacts.

3. Config is just "config": {} — no fields required.

CardDAV

Works with any CardDAV server — Fastmail, Nextcloud, Radicale, iCloud, etc.

For iCloud: use an app-specific password and https://contacts.icloud.com as the server URL.

How Dedup Works

The find_duplicates tool compares contacts using weighted field matching:

Contacts are grouped into blocking keys (by name initials, email domain, phone suffix) before comparison, so performance stays fast even with thousands of contacts.

The default threshold is 0.6 — anything scored at or above that is reported as a potential duplicate.

How Merge Works

merge_contacts takes 2+ contact IDs and combines them:

• First ID is the primary — it keeps its UUID, the others are archived.

• union strategy (default) — combines all emails, phones, addresses, URLs, categories. Takes the longer/more complete name. Picks up birthday, org, photo from whichever has it.

• keep-newest — takes all fields from the most recently modified contact.

• keep-oldest — takes all fields from the earliest modified contact.

• fieldOverrides — manually specify which contact's value to use for specific fields: { "organization": "uuid-of-contact-with-better-org" }.

• Provider IDs are merged — so if contact A was from Google and contact B was from CardDAV, the merged contact maps to both remotes.

How Sync Works

Sync is local-first and explicit (triggered by the sync_provider tool, never automatic):

1. Pull: Fetch contacts from the remote. New ones are imported locally. Changed ones are updated based on conflict strategy.

2. Push: Local contacts modified since last sync are pushed to the remote. New local contacts get created remotely.

3. Conflict resolution (when both sides changed):

   • newest-wins (default) — compare modification timestamps, keep the newer one.

   • local-wins — always keep the local version.

   • remote-wins — always accept the remote version.

   • manual — flag as conflict, don't auto-resolve.

4. Pre/post sync git tags are created for rollback.

Project Structure

src/
├── index.ts                # Entry point — stdio transport
├── server.ts               # McpServer setup, wires tools + resources
├── config.ts               # Config loading from file / env vars
├── types/                  # TypeScript interfaces (Contact, Provider, etc.)
├── contacts/
│   ├── model.ts            # Contact construction + name parsing
│   ├── vcard.ts            # vCard 4.0 serialize/deserialize (no external lib)
│   ├── normalize.ts        # Phone (E.164), email, name normalization
│   ├── search.ts           # Fuse.js fuzzy search
│   ├── dedup.ts            # Duplicate detection with weighted scoring
│   └── merge.ts            # Contact merge with multiple strategies
├── store/
│   ├── git-ops.ts          # Low-level git wrapper (simple-git)
│   ├── git-store.ts        # CRUD + bulk ops + history + rollback
│   └── file-layout.ts      # Path conventions
├── providers/
│   ├── base.ts             # Abstract provider
│   ├── google.ts           # Google People API
│   ├── apple.ts            # macOS Contacts via JXA
│   ├── carddav.ts          # CardDAV via tsdav
│   └── local.ts            # Local store wrapper
├── sync/
│   ├── engine.ts           # Bidirectional sync orchestration
│   ├── conflict.ts         # Conflict resolution
│   └── diff.ts             # Field-level contact diffing
├── tools/                  # One file per MCP tool (13 tools)
└── resources/              # MCP resource handlers (4 resources)

Tech Stack

License

MIT