Contacts MCP

联系mcp

一个MCP服务器，为人工智能助手提供全面的联系人管理功能——创建、搜索、重复数据删除、合并、跨系统同步，并自信地回滚任何更改。

联系人作为单独的vCard文件存储在git存储库中。每个变异都是一个git提交，所以你可以免费获得完整的版本历史、差异和恢复。人工智能可以做出彻底的改变，知道一切都是可以恢复的。

快速开始

先决条件

• 包子 1.0+
• Git（在PATH中可用）

安装和构建

cd contacts-mcp
bun install
bun run build

添加到克劳德代码

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

添加到克劳德桌面

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

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

发展模式

直接从源代码运行，无需构建（bun本机运行TypeScript）：

bun run dev

验证它是否有效

使用MCP检查器进行交互式测试：

bunx @modelcontextprotocol/inspector bun dist/index.js

它做什么

一旦连接，您的AI助手将获得14个工具和4个资源来管理联系人：

工具

CLI导出和解析

默认情况下，二进制文件仍会启动MCP stdio服务器。它还支持确定性 其他本地工具的非AI命令行操作：

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 输入是JSON：

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

使用 CONTACTS_MCP_STORE=/path/to/store 导出或解决自定义问题时 商店路径。

在从macOS导出联系人之前，将Apple Contacts拉入本地git支持 商店：

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

如果您没有Apple提供商 ~/.contacts-mcp/config.json，CLI将使用 macOS上的内置苹果提供商。第一次运行可能会触发联系人权限 提示。

资源

存储工作原理

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

• 每个联系人一个文件 --每个联系人都是一个标准vCard 4.0(.vcf)以UUID命名的文件。
• 每一次改变都是一次承诺 --创建、更新、删除、合并、导入所有生成描述性git提交，如 Create contact: Jane Smith (uuid) 或 Merge contacts: Jane + J. Smith -> Jane Smith.
• 软删除 — delete_contact 从以下位置移动文件 contacts/ 到 archive/。它仍在回购中，可以通过以下方式找到 get_contact 或通过回滚恢复。
• 批量操作获取标签 --导入和同步创建 pre-import- / post-import- git标签，这样你就可以一次性回滚整个批量操作。
• 回滚=git恢复 --总是创建新的提交（从不 reset --hard)，因此完整的审计跟踪得以保留，回滚本身也是可逆的。

配置

配置从加载 ~/.contacts-mcp/config.json （或路径在 CONTACTS_MCP_CONFIG 有人）。

最小配置（仅限本地）

不需要配置文件。服务器可以开箱即用，本地git存储在 ~/.contacts-mcp/store/.

自定义存储路径

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

或者通过环境变量：

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

与提供商完全配置

{
  "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": {}
    }
  ]
}

环境变量

提供商设置

Google 通讯录

使用Google People API。您需要OAuth2凭据：

1. 首选 谷歌云控制台 并创建一个项目。
2. 启用 人民API.
3. 创建OAuth2凭据（桌面应用程序类型）。
4. 使用OAuth2游乐场或脚本获取刷新令牌 https://www.googleapis.com/auth/contacts 范围。
5. 添加 clientId, clientSecret，以及 refreshToken 到你的配置。

苹果联系人（仅限macOS）

通过以下方式使用JavaScript进行自动化（JXA） osascript.不需要凭据，但是：

1. 首次同步时，macOS将提示您允许终端/IDE访问联系人。
2. 授予权限 系统设置>隐私和安全>联系人.
3. 配置只是 "config": {} --不需要字段。

CardDAV

适用于任何CardDAV服务器——Fastmail、Nextcloud、Radical、iCloud等。

对于 苹果云：使用 应用程序特定密码 和 https://contacts.icloud.com 作为服务器URL。

除尘工作原理

这 find_duplicates 该工具使用加权字段匹配来比较联系人：

联系人分组为 屏蔽键 （按姓名首字母、电子邮件域、电话后缀）进行比较，因此即使有数千个联系人，性能也会保持快速。

默认阈值为0.6——任何得分等于或高于0.6的东西都被报告为潜在的重复。

合并是如何工作的

merge_contacts 获取2+个联系人ID并将其组合：

• 第一个ID是主要ID --它保留其UUID，其他UUID则存档。
• union 策略 （默认）--组合所有电子邮件、电话、地址、URL、类别。使用更长/更完整的名称。从任何有生日、组织、照片的地方获取。
• keep-newest --从最近修改的联系人中获取所有字段。
• keep-oldest --获取最早修改的联系人的所有字段。
• fieldOverrides --手动指定将哪个联系人的值用于特定字段： { "organization": "uuid-of-contact-with-better-org" }.
• 提供商ID已合并 --因此，如果联系人A来自谷歌，联系人B来自CardDAV，则合并后的联系人映射到两个遥控器。

Sync的工作原理

同步是 本地优先 和 明确的 （由触发 sync_provider 工具，从不自动）：

1. 拉：从远程获取联系人。新的是从当地进口的。更改后的内容将根据冲突策略进行更新。
2. 推：自上次同步以来修改的本地联系人被推送到远程。远程创建新的本地联系人。
3. 冲突解决 （当双方都发生变化时）：

- newest-wins （默认）--比较修改时间戳，保留较新的时间戳。 - local-wins --始终保持本地版本。 - remote-wins --始终接受远程版本。 - manual --标记为冲突，不要自动解决。

1. 创建同步前/同步后的git标签用于回滚。

项目结构

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)

技术栈

许可证

麻省理工学院