samecontact

samecontact：查找 CSV 文件中的重复客户和联系人

通过查找代表同一个人的行，清理 CRM 导出文件、客户列表或邮件列表，即使姓名、电子邮件或电话号码的写法不同也能识别。适用于小型企业、销售团队和营销人员。

大多数客户列表中，同一个人会出现好几次：“Robert Jones”和“Bob Jones”，或 Ana.Silva+news@ 和 ana.silva@。重复记录会增加邮件发送成本、惹恼客户，还会夸大数据，而在电子表格中简单去重会漏掉大多数重复项。samecontact 会比较电子邮件、电话号码、姓名和公司，然后说明判断的把握程度及原因。它不会自行合并任何内容。它既是 MCP 服务，也是一个独立的 Go 二进制文件，无需账户、API 密钥，也不会访问网络。

可以向你的 Agent 提出什么请求

• “找出我的客户列表中的重复记录。”
• “我实际有多少位独立客户？”
• “在导入之前清理这份 HubSpot 或 Salesforce 导出文件。”
• “这份邮件列表中，哪些联系人是同一个人？”

安装

作为 Claude Code 插件安装，它会添加 MCP 服务和一项技能，告诉 Claude 何时使用该服务。你需要安装 Node，以便通过 npx 运行服务：

claude plugin marketplace add GillMacedo/samecontact
claude plugin install samecontact@samecontact-marketplace

对于其他 MCP 客户端：

{
  "mcpServers": {
    "samecontact": {
      "command": "npx",
      "args": ["-y", "samecontact", "serve"]
    }
  }
}

npm 安装适用于 macOS 和 Linux。Windows 用户目前请使用 go install。

或者使用 Go 1.27 或更高版本构建二进制文件：

go install github.com/GillMacedo/samecontact@latest

用法

试用 examples/ 中的示例文件。其中所有人物都是虚构的。

$ go run . find examples/contacts.csv
SAME PERSON (2)
  rows 3, 4  Ana Silva / Silva, Ana  [same email; same name and company]
  rows 5, 6  Robert Jones / Bob Jones  [same phone and matching name]
LIKELY: check these (1)
  rows 7, 8  Maria Costa  [same name and company]
REVIEW: a person should decide (2)
  rows 11, 12  John Smith / John Smith  [same name, different companies]
  rows 13, 14  Lena Fischer / Omar Haddad  [same email, different names: may be a shared address]
SKIPPED row 16: no name, email or phone
13 contacts, 3 duplicate groups, 3 extra rows, 2 pairs to review

安装后，运行 samecontact find contacts.csv。添加 --out marked.csv，即可写入一份包含 dup_group 和 dup_level 列的副本，可在电子表格中排序。原文件绝不会被修改。添加 --json 可输出机器可读的结果。

判断依据

级别	证据
同一个人	电子邮件相同且姓名匹配、电话号码相同且姓名匹配，或整行完全相同
很可能	姓名和公司相同、姓名相同且工作邮箱域名相同，或电话号码相同但其中一方缺少姓名
需要复核	一个电子邮件或电话号码对应不同姓名、只有姓名相同，或同一公司中姓名相似

它能识别昵称、姓名首字母、重音符号、姓名顺序、小拼写错误、电话号码格式、Gmail 地址中的点和 +tags。像 info@ 这样的地址和 Gmail 等免费域名，不能作为判定为同一个人的证据。

MCP 工具

工具	功能
contacts_find_duplicates	返回重复组和待复核的匹配对；针对大文件提供数量限制
contacts_inspect_csv	显示检测到的列和行数，不包含行内容

这两个工具均为只读。contacts_find_duplicates 会将文件中的姓名返回给 MCP 客户端，因此这些姓名会传递给你使用的 AI 模型。CLI 会将所有数据保留在你的计算机上。

常见问题

如何从 CSV 中删除重复联系人？ 运行 samecontact find contacts.csv --out marked.csv，检查分组，然后在 CRM 或电子表格中删除或合并行。此工具不会删除任何内容。

它能处理 HubSpot、Salesforce 或 Mailchimp 导出的数据吗？ 它可以读取 CSV 并识别常见列名，你也可以使用 --columns email=Mail,name=Who 指定其他列名。目前尚未针对这些产品的实际导出文件逐一测试。

我的客户数据会被上传吗？ 此工具不包含网络代码。通过 MCP，结果会发送给客户端使用的 AI 模型。

限制

• 它会找出可能重复的联系人，但在合并任何内容前，应由人工检查。
• 名称匹配针对西方姓名和常见昵称设计，因此可能无法识别其他命名体系中的某些变体。
• 电话号码按末尾 10 位进行比较，因此不同国家的两个号码可能被判定为重复。
• 它仅支持读取 CSV，文件大小上限为 50 MB。
• 目前只用虚构数据进行过测试，尚未测试实际导出文件。如果你的文件处理失败，请提交 issue 并附上列标题，不要附上数据。

参与贡献

欢迎个人以及与 AI Agent 协作的人参与贡献。请参阅 CONTRIBUTING.md。适合新手的首批任务：

• 添加更多 CRM 和语言的列名
• 添加更多昵称，包括非英语昵称
• 添加 XLSX 读取器
• 添加一个 merge 命令，为每个分组生成一行合并建议
• 添加插件图标

Pull request 的处理方式

1. 提交 PR。 Fork 仓库，在分支上开发，并将 PR 限定为一项更改。标题应说明用户会看到哪些变化，因为它会成为变更日志条目：feat: 会归入 Added，fix: 会归入 Fixed。
2. 自动检查。 代码更改需要附带测试，且 make test 必须通过。超过 30 行的更改需要关联一个已开启的 issue（Closes #<number>），PR 的更改行数最多为 800 行。如果有缺漏，系统会通过评论告知需要修正的内容。
3. 审核。 Claude 会自动审核每个 PR。代码 PR 还会接受安全审核，并在沙箱中进行测试。之后，审核流程会合并 PR 或要求修改。更改 CI、Agent 设置、npm 或 Python 依赖、供应商代码或构建文件的 PR 无法通过此流程合并，系统会通过评论说明。同样，安全审核未通过的更改也无法合并。
4. 发布。 会改变用户安装内容的合并更改将在大约两小时内发布为新版本，并附带 GitHub Release，以及项目提供的 npm 包（如有）。文档和 CI 更改则会等到下一次发布。

AI 使用说明

本项目大部分由 Claude Code 生成，并由维护者审核。

关于我

我是 Giulliano Macedo，在 GoTech Solutions 构建开发者工具。欢迎关注我或与我联系：

• GitHub：GillMacedo
• LinkedIn：giulliano
• X：@giumacedo

如果 samecontact 帮你清理了列表，点个星标可以让更多人发现它。

---

采用 MIT 许可证。

由 Giulliano Macedo、GoTech Solutions 构建 · LinkedIn · X