# Apple Contacts

This MCP server lets an agent look up people in the macOS address book and match phone numbers or email addresses to names. Contact changes stay hidden unless writes are enabled.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: mgcrea
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mgcrea/cupertino/tree/HEAD/packages/contacts
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/mgcrea-apple-contacts

## What it does

Apple Contacts exposes tools for reading and finding address book entries. An agent can match a phone number or email address to a name, search contacts, list entries, and retrieve an individual record. When a match is uncertain, the server reports that state instead of choosing a person.

Creating and editing entries require `APPLE_CONTACTS_ALLOW_WRITES=1`. With that setting off, write tools are not exposed to the agent. macOS asks for Contacts access when the server reads the address book; approve the system prompt to proceed.

The server reads contacts stored on the Mac and handles more than one contact store. When writes are enabled, each change is saved and then read back. That matters because an edit can appear during a script run without having reached the address book store.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `APPLE_CONTACTS_ALLOW_WRITES` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> --transport stdio contacts -- npx -y @mgcrea/mcp-apple-contacts
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add contacts --env APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> -- npx -y @mgcrea/mcp-apple-contacts
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "contacts": {
            "command": "npx",
            "args": [
                "-y",
                "@mgcrea/mcp-apple-contacts"
            ],
            "env": {
                "APPLE_CONTACTS_ALLOW_WRITES": "<APPLE_CONTACTS_ALLOW_WRITES>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "contacts": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@mgcrea/mcp-apple-contacts"
            ],
            "env": {
                "APPLE_CONTACTS_ALLOW_WRITES": "<APPLE_CONTACTS_ALLOW_WRITES>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e APPLE_CONTACTS_ALLOW_WRITES=<APPLE_CONTACTS_ALLOW_WRITES> contacts npx -y @mgcrea/mcp-apple-contacts
```
Replace <…> with your own values

## When to use it
- Match a phone number to a contact name
- Identify the person behind an email address
- Search the macOS address book
- Retrieve a specific contact record
- Create or edit an entry with writes enabled

## Example prompts
- Find the contact with the email address `alex@example.com`.
- Match these phone numbers to names and show any ambiguous results.
- Create a contact named Alex with the phone number `+1...`.

## Similar
- [REA](https://affpapa.org/en/nevibecode/mcp/rea.md) — MCP server · ★ 392262
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33989
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81163
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119231
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47577
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43902

## Other versions with the same name
- [Apple Contacts · jonathanrreed](https://affpapa.org/en/nevibecode/mcp/apple-contacts.md) — ★ 31

From the same set: [mgcrea/cupertino](https://affpapa.org/en/nevibecode/by/mgcrea/cupertino.md) — 6 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md