Contactbook 📇 — Apple Contacts CLI + MCP server

Contactbook brings Apple Contacts automation to macOS through a Swift CLI and MCP server. List, search, create, update, and delete contacts — from the terminal or any MCP client.

What you get

| Feature | Description | |---------|-------------| | List Contacts | Browse all contacts with optional limit | | Search Contacts | Find by name, email, phone, or organization | | Get Contact | Retrieve full contact details by ID | | Create Contact | Add new contacts with all fields | | Update Contact | Modify existing contact properties | | Delete Contact | Remove contacts (with confirmation) | | Groups | List groups and group members | | Lookup | Quick lookup by name or identifier | | MCP Server | All features exposed as MCP tools for AI agents |

Install

# Clone and build
git clone https://github.com/RyanLisse/Contactbook.git
cd Contactbook
swift build -c release

# Install to PATH
cp .build/release/contactbook /usr/local/bin/contactbook

Quick start

# List contacts
contactbook contacts list --limit 10

# Search contacts
contactbook contacts search "John"

# Get contact by ID
contactbook contacts get <contact-id> --json

# Create a contact
contactbook contacts create \
  --firstName "John" \
  --lastName "Doe" \
  --email "john@example.com" \
  --phone "+1234567890"

# Update a contact
contactbook contacts update <contact-id> --jobTitle "Engineer"

# Delete a contact
contactbook contacts delete <contact-id> --force

# List groups
contactbook groups list

# Quick lookup
contactbook lookup "John Doe"

| Command | Key flags | What it does | |---------|-----------|--------------| | contacts list | --limit, --json | List all contacts | | contacts search | <query>, --json | Search contacts | | contacts get | <id>, --json | Get contact by ID | | contacts create | --firstName, --lastName, etc. | Create new contact | | contacts update | <id>, field options | Update contact | | contacts delete | <id>, --force | Delete contact | | groups list | --json | List all groups | | groups members | <group-id> | List group members | | lookup | <query> | Quick name/ID lookup | | mcp serve | - | Start MCP server |

MCP Server

Start the MCP server for AI agent integration:

contactbook mcp serve

MCP Tools

| Tool | Description | |------|-------------| | contacts_list | List all contacts | | contacts_search | Search contacts by query | | contacts_get | Get contact by ID | | contacts_create | Create new contact | | contacts_update | Update existing contact | | contacts_delete | Delete contact | | groups_list | List all groups | | groups_members | Get group members |

Claude Desktop Config

{
  "mcpServers": {
    "contactbook": {
      "command": "/usr/local/bin/contactbook",
      "args": ["mcp", "serve"]
    }
  }
}

Architecture

Follows the Peekaboo architecture standard:

Sources/
├── Core/           # ContactbookCore - framework-agnostic library
│   ├── Models/     # Contact, ContactGroup models
│   ├── Services/   # ContactsService (Contacts framework wrapper)
│   └── Errors/     # ContactsError
├── CLI/            # ContactbookCLI - ArgumentParser commands
│   └── Commands/   # Contacts, Groups, Lookup, MCP commands
├── MCP/            # ContactbookMCP - MCP server with handler pattern
│   └─

... [View full README on GitHub](https://github.com/RyanLisse/Contactbook#readme)