mcp-intercom

在客户服务领域，快速定位与客户的历史聊天记录往往是解决当前问题的最快捷径。然而，当数据量庞大时，手动筛选对话不仅耗时，还容易遗漏关键信息。这就是 mcp-intercom 要解决的核心痛点。

mcp-intercom 是一个基于模型上下文协议（MCP）的服务器，它充当了大型语言模型（LLM）与 Intercom 客服系统之间的桥梁。通过它，你可以直接用自然语言指令让 AI 帮你查询、分析 Intercom 中的对话，将原本需要编写 API 或手动翻页的操作，简化为一句简单的话。

项目基本信息

一、项目介绍

mcp-intercom 是一个专门为 Intercom 设计的 MCP 服务器。简单来说，它定义了一套规则，让像 Claude 这样的 AI 模型能够通过标准的接口去访问你的 Intercom 数据。

它的工作方式很直接：你启动这个服务器，它会提供一个名为 search-conversations 的工具给 AI 模型。当你问 AI “帮我找找上个月所有未读的邮件对话”时，AI 就会调用这个工具，传入“上个月”、“未读”、“邮件”等参数，然后服务器从 Intercom 拉取数据并返回给 AI。最终，AI 将结果组织成你容易理解的回答。

这个项目完全用 TypeScript 编写，保证了类型的严谨和代码的可维护性。它并不是一个面向最终用户的图形界面软件，而是一个后台服务，非常适合集成到现有的 AI 工作流或自动化系统中。

二、核心优势

灵活且强大的筛选能力
它提供的 search-conversations 工具支持多种筛选条件，包括按创建/更新时间、来源类型（邮件、在线聊天）、对话状态（开启、关闭）、是否已读等。你可以组合这些条件，实现非常精准的查询。

安全且只读的设计
该服务器仅请求读取对话的权限，不会对 Intercom 中的任何数据进行修改或删除。你的 API 密钥通过环境变量传入，避免了硬编码，降低了泄露风险。

无缝集成 AI 应用
它符合 MCP 协议，可以轻松接入支持该协议的 AI 客户端，如 Claude for Desktop。这让非技术用户也能通过自然语言与复杂的客服数据交互，极大降低了使用门槛。

基于 TypeScript，易于扩展
项目代码结构清晰，使用 TypeScript 编写。如果你有编程基础，可以很方便地克隆、修改或增加新的功能，例如增加更新会话状态的能力。

三、适用场景

• 客服质量分析：管理者可以询问 AI “列出本周所有优先级为紧急且已关闭的对话”，快速抽检客服团队的回复质量。
• 用户问题归类：开发者可以编写脚本定期拉取特定时间段内的对话，交由 AI 进行聚类分析，找出用户最常见的几类问题。
• 构建智能客服助手：将 mcp-intercom 集成到公司内部的管理后台中，让运营人员可以用自然语言查询用户历史，例如“查找 customer_id 为 12345 的用户过去三个月的所有对话”。
• 自动化报告生成：结合定时任务（如 cron job），每天自动查询昨日新增的未解决对话数量，并生成报告发送到内部协作平台。

四、安装教程

安装 mcp-intercom 需要你的系统已安装 Node.js（版本 14.0 或以上）和 Git。以下是完整步骤：

第一步：克隆项目代码

打开终端，执行以下命令将项目仓库复制到本地：

git clone https://github.com/fabian1710/mcp-intercom.git
cd mcp-intercom

第二步：安装依赖

项目依赖管理使用 npm，执行安装命令：

npm install

第三步：配置环境变量

项目提供了一个环境变量模板文件。复制它并编辑：

cp .env.example .env

然后，用文本编辑器打开 .env 文件，填入你的 Intercom API 密钥。

INTERCOM_API_KEY=你的实际API密钥

重要提示：你需要登录 Intercom 后台，进入“设置” -> “应用与集成” -> “访问令牌”来生成一个具有读取对话权限的访问令牌。

第四步：构建项目

由于项目是 TypeScript 编写的，需要编译成 JavaScript：

npm run build

编译成功后，会在 dist 目录下生成可执行文件。

第五步：启动服务器

npm start

如果看到类似 “MCP server running...” 的日志，说明服务器已成功启动，等待接受来自 AI 的连接。

五、使用示例

以下是将 mcp-intercom 与 Claude for Desktop 集成的完整示例，这是最典型的应用场景。

1. 配置 Claude Desktop

找到 Claude for Desktop 的配置文件，通常在：

• Windows: %AppData%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

用编辑器打开它，添加一个名为 intercom 的新服务器条目。请务必将路径改为你的实际项目路径。

{
  "mcpServers": {
    "intercom": {
      "command": "node",
      "args": ["/你的完整路径/mcp-intercom/dist/index.js"],
      "env": {
        "INTERCOM_API_KEY": "你的实际API密钥"
      }
    }
  }
}

保存文件并完全重启 Claude for Desktop。

2. 在 Claude 中查询对话

重启后，在 Claude 的对话框右侧应能看到一个插头图标，表示 MCP 工具已连接。现在你可以开始提问了。

• 查询最近对话

输入：帮我搜索所有在 2026年3月1日 之后创建的对话。

Claude 将调用 search-conversations 工具，并最终返回一个包含对话列表的回答。

• 组合筛选条件

输入：查找所有状态为开启 (open) 且来源是邮件 (email) 的未读会话。

Claude 会将你的自然语言需求转换为对应的参数，返回精确结果。

六、常见问题

问题1：启动 Claude 后看不到工具连接图标？

• 解决方案：首先检查 JSON 配置文件格式是否正确，特别是路径和逗号。其次，确保已完全退出 Claude 程序并重新启动。最后，检查终端中是否有进程在运行，可以尝试手动运行 node /你的路径/dist/index.js 看是否有报错。

问题2：查询时提示“认证失败”或“无效的 API 密钥”？

• 解决方案：请确认你的 Intercom API 密钥具有读取对话的权限。进入 Intercom 后台重新生成一个密钥，并确保 .env 文件或 Claude 配置中的 INTERCOM_API_KEY 值已正确更新。

问题3：返回结果不完整或为空，但我确定有数据？

• 解决方案：检查你的筛选条件。Intercom API 对日期范围、状态等有特定格式要求。尝试先用最简单的条件（例如不加任何日期限制）进行测试，确认能获取数据后，再叠加筛选条件。

问题4：安装依赖时 npm install 报错？

• 解决方案：这通常是由于网络问题或 Node.js 版本过低。请先执行 node -v 确认版本为 v14 或以上。如果网络不佳，可以尝试使用国内镜像源，例如 npm install --registry=https://registry.npmmirror.com。

七、总结

mcp-intercom 是一个精巧且实用的项目，它展现了 MCP 协议在连接 AI 与现有业务数据方面的巨大潜力。通过将复杂的 API 调用封装成自然语言指令，它极大地提升了客服数据查询和分析的效率。

对于使用 Intercom 的团队或个人开发者来说，这是一个“小而美”的工具，值得立即集成到工作流中。它不仅能节省处理数据的时间，还能基于数据做出更快的决策。考虑到其开源和 MIT 许可的特性，你完全可以根据自己的需求进行定制和扩展。

如果你正苦于如何让 AI 安全、高效地访问你的客服对话数据，mcp-intercom 无疑是一个绝佳的起点。