cosmic-grackle

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