cosmic-grackle

[!WARNING] This MCP can permanently modify or delete contacts in your local macOS address book. The mutating tools (contacts_create, contacts_update, contacts_delete) write directly to CNContactStore — there is no undo. Before using this plugin, back up your contacts (Contacts.app → File → Export → Contacts Archive, or sync to iCloud) and approve each mutating action individually rather than running this in any auto-approve / YOLO mode. An LLM that misreads a request can clobber the wrong record just as easily as the right one.

A macOS Contacts MCP server written in Rust, plus a companion macos-contacts skill for Claude Code. Exposes the local Apple Contacts database (CNContactStore) over the Model Context Protocol (MCP) so Claude can read, search, and CRUD entries on the user's Mac. Applies only to the native macOS Contacts app — not Google Contacts, iCloud.com, Outlook, or third-party CRMs.

What it does

This repo distributes two independent pieces: a stdio MCP server (the cosmic-grackle binary) and a skill (macos-contacts) delivered through the Claude Code plugin marketplace. The server exposes the contact tools; the skill teaches Claude when they apply, the safe workflow (search → confirm → mutate; confirm-before-delete), and how to recover from permission denials. Together they let a Claude conversation do things like "add Ada Lovelace to my contacts," "change Bob's mobile number to 555-0200," or "find everyone in my Family group."

Every contact carries an opaque id. Updates and deletes work by id, never by name — two people can share a name, so the workflow always resolves an id with contacts_search (or contacts_list) and disambiguates with the user before mutating. contacts_get returns the canonical stored form of a record, which matters because the _from/_to update ops match _from exactly against the stored value.

What it can't do: rename entry labels (e.g., switch a phone from "mobile" to "work"), add or remove members from a group, or operate on contact stores other than the local Mac. Those require Contacts.app or a different integration.

Requirements

• macOS (uses the native Contacts framework)
• Rust 1.95+ (only when building from source)
• Contacts access permission (prompted on first tool call; granted to bundle ID me.ngerakines.cosmic-grackle)

Building

cargo build --release

Install the MCP server

The server and the skill are distributed independently. You install the binary; you wire it into whichever MCP client you use; then (optionally) you install the skill so the model knows how to drive the tools safely.

Homebrew install is forthcoming and will be linked here once the formula is published.

Until then, download the per-arch tarball from the latest GitHub release:

# Apple Silicon
curl -fL -o cosmic-grackle.tar.gz \
  https://github.com/ngerakines/cosmic-grackle/releases/latest/download/cosmic-grackle-darwin-arm64.tar.gz
# or Intel
curl -fL -o cosmic-grackle.tar.gz \
  https://github.com/ngerakines/cosmic-grackle/releases/latest/download/cosmic-grackle-darwin-amd64.tar.gz

tar -xzf cosmic-grackle.tar.gz
xattr -d com.apple.quarantine ./cosmic-grackle 2>/dev/null || true
sudo mv ./cosmic-grackle /usr/local/bin/   # or anywhere on $PATH

Then register it with your MCP client. For Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "contacts": {
      "command": "/usr/local/bin/cosmic-grackle"
    }
  }
}

For Claude Code, add to your project or user .mcp.json:

{
  "mcpServers": {
    "contacts": {
      "type": "stdio",
      "command": "/usr/local/bin/cosmic-grackle"
    }
  }
}

Restart the client. The first contacts tool call triggers the macOS Contacts permission prompt; grant access in System Settings → Privacy & Security → Contacts.

Install the skill (optional, Claude Code only)

The macos-contacts skill is a prompt-only guide that teaches Claude the safe workflow (search → confirm → mutate; confirm-before-delete; phone/email matching rules). It is not required for the tools to work, but it materially improves correctness on mutating operations. The skill is delivered through the Claude Code plugin marketplace:

/plugin marketplace add ngerakines/cosmic-grackle
/plugin install cosmic-grackle@cosmic-grackle

This adds the skill text only — it does not install the MCP server. If you skipped the previous section, the skill will load but the contacts tools won't exist in your session.

The Claude Desktop Settings → Connectors / Skills panel cannot drive a local stdio MCP server; use Claude Code for the skill, or just rely on the README's pitfalls section if you only use Claude Desktop.

Tools

Read-only

Tool	Purpose
contacts_list	List contacts, optionally capped by limit. Returns full records including the opaque id required by update / delete.
contacts_search	Search by name substring. Primary way to resolve an id. If multiple matches, the workflow asks the user which one.
contacts_get	Read a single contact by id in canonical stored form. Call this before any _from/_to update so the match value is exact, and before any delete to show the user what's about to be removed.
groups_list	List every group with member counts.
groups_members	Return contacts in a named group (case-insensitive).

Mutating

Tool	Purpose
contacts_create	Create a contact. At least one of first_name, last_name, or organization is required. Accepts a full set of name / phonetic / organization fields plus one each of phone, email, url, and postal_address (each gets the default label — mobile / work / homepage / home). Use contacts_update afterward to add more entries.
contacts_update	Partial update by id. Scalar fields (names, organization, job_title, note, birthday, etc.) overwrite directly. Phones, emails, URLs, and postal addresses use paired phone_from/phone_to, email_from/email_to, url_from/url_to, postal_from/postal_to ops: _to only adds, _from only removes, both replaces in place. Matching is exact against the stored form.
contacts_delete	Delete a contact by id. Permanent — the workflow shows the full record and gets explicit user confirmation first.

See plugin/skills/macos-contacts/SKILL.md for the full workflow, length caps, and worked examples.

Permissions

The first tool call after install triggers the macOS Contacts permission prompt. If access is denied, subsequent calls return an internal error. To recover: open System Settings → Privacy & Security → Contacts, enable access for the invoking process (typically cosmic-grackle or the parent Claude app), then restart Claude so the MCP server relaunches with the new entitlement.

License

Licensed under the MIT License.