Intercom Articles MCP

🚀 Intercom MCP 服务器

Intercom MCP 服务器用于帮助中心内容管理和客户支持（CS）工作流自动化。它可以高效地管理帮助中心的文章和集合，同时实现 CS 工作流的自动化操作。

🚀 快速开始

Intercom MCP 服务器助力帮助中心内容管理与 CS 工作流自动化。以下是快速上手步骤：

1. 克隆仓库：

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

2. 安装依赖：

npm install

3. 构建项目：

npm run build

✨ 主要特性

文章管理

• ✅ get_article - 通过 ID 获取单篇文章
• ✅ list_articles - 分页列出文章
• ✅ search_articles - 通过关键词搜索文章，支持高亮显示
• ✅ create_article - 创建包含多语言内容的新文章
• ✅ update_article - 部分更新现有文章

集合管理

• ✅ list_collections - 列出所有帮助中心集合
• ✅ get_collection - 通过 ID 获取单个集合
• ✅ update_collection - 更新集合信息和翻译内容
• ✅ delete_collection - 永久删除集合

CS 工作流

• ✅ reply_conversation - 以管理员身份回复对话
• ✅ add_conversation_note - 为对话添加内部备注
• ✅ close_conversation - 关闭对话
• ✅ update_ticket - 更新工单的状态或属性

📦 安装指南

克隆仓库

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

安装依赖

npm install

构建项目

npm run build

📚 详细文档

配置

获取 Intercom 访问令牌

1. 前往 Intercom 设置 → 开发者 → 开发者中心。
2. 创建新应用或使用现有应用。
3. 获取具有 文章 和 对话 读写权限的访问令牌。

环境变量

变量	是否必需	描述
INTERCOM_ACCESS_TOKEN	✅ 始终需要	你的 Intercom API 访问令牌
INTERCOM_ADMIN_ID	✅ 用于 CS 工具	当未提供 admin_id 参数时，reply_conversation 和 add_conversation_note 使用的管理员 ID

使用 Claude Code 进行配置（推荐）

如果你使用 Claude Code CLI，可以轻松添加 MCP 服务器：

claude mcp add --transport stdio intercom-mcp \
  --env INTERCOM_ACCESS_TOKEN=<your_token> \
  --env INTERCOM_ADMIN_ID=<your_admin_id> \
  -- node /ABSOLUTE/PATH/TO/intercom-mcp/dist/index.js

替换：

• <your_token> 为你的 Intercom 访问令牌
• /ABSOLUTE/PATH/TO/ 为你的实际项目路径

验证配置：

claude mcp list

手动配置 Claude 桌面版

编辑 Claude 桌面版配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

添加以下配置：

{
  "mcpServers": {
    "intercom-mcp": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/intercom-mcp/dist/index.js"
      ],
      "env": {
        "INTERCOM_ACCESS_TOKEN": "your_intercom_access_token_here",
        "INTERCOM_ADMIN_ID": "your_admin_id_here"
      }
    }
  }
}

重要提示：

• 将 /ABSOLUTE/PATH/TO/intercom-mcp 替换为你的实际项目路径
• 将 your_intercom_access_token_here 替换为你的实际令牌
• 将 your_admin_id_here 替换为你的 Intercom 管理员 ID（CS 工具需要）

重启 Claude 桌面版

完全退出 Claude 桌面版并重新启动。

使用方法

配置完成后，你可以在 Claude 桌面版中使用以下命令：

列出文章

List Intercom articles

或

Show me the first 20 Intercom articles

获取文章详情

Get Intercom article with ID 9876543

搜索文章

Search for Intercom articles about "subscription"

或

Search published articles containing "播客" with highlighted matches

或

Find articles with keyword "訂閱" in Chinese

创建文章

Create a new Intercom article titled "Getting Started Guide" with content "Welcome to our platform" by author ID 123456, save as draft

更新文章

Update article 9876543 and change its state to published

列出集合

List all Intercom Help Center collections

获取集合

Get collection with ID 14608214

更新集合

Update collection 14608214 and add Japanese translation

删除集合

Delete collection 16036040

用例：翻译管理

v0.4.0 的一个关键特性是能够高效管理多语言集合。

添加缺失的翻译

你可以轻松为缺少某些语言的集合添加翻译：

Update collection 14608214 and add the missing Japanese translation: name "アカウント管理", description "アカウント設定を管理する"

批量翻译更新

检查哪些集合缺少翻译：

List all collections and show me which ones are missing Japanese translations

然后逐个更新或制定更新多个集合的计划。

验证翻译

更新后，验证更改：

Get collection 14608214 and show me all available translations

工具参考

get_article

通过 ID 获取单篇文章。 参数：

• id（字符串，必需）：文章 ID

示例：

{
  "id": "9876543"
}

list_articles

分页列出文章。 参数：

• page（数字，可选）：页码（默认：1）
• per_page（数字，可选）：每页文章数（默认：10，最大：50）

示例：

{
  "page": 1,
  "per_page": 20
}

search_articles

使用关键词搜索文章。支持跨文章内容的全文搜索，具备多语言支持（英语、中文、日语等）。 参数：

• phrase（字符串，必需）：在文章中查找的搜索关键词/短语
• state（字符串，可选）：按文章状态过滤 - "published"、"draft" 或 "all"（默认："all"）
• help_center_id（字符串，可选）：按特定帮助中心 ID 过滤
• highlight（布尔值，可选）：返回高亮显示的匹配内容片段（默认：false）

示例（简单搜索）：

{
  "phrase": "subscription"
}

示例（带过滤条件的搜索）：

{
  "phrase": "播客",
  "state": "published",
  "highlight": true
}

示例（中文关键词搜索）：

{
  "phrase": "訂閱制",
  "state": "all",
  "highlight": true
}

响应包含：

• total_count：匹配文章的总数
• data.articles：包含完整内容的匹配文章数组
• pages：包含下一页 URL 的分页信息
• 高亮显示的内容片段（当 highlight: true 时）

用例：

• 查找关于特定主题的所有文章
• 在多语言帮助中心搜索中文/日语内容
• 定位需要更新的文章
• 发现用于交叉链接的相关内容

create_article

创建支持多语言的新文章。 参数：

• title（字符串，必需）：文章标题
• body（字符串，必需）：HTML 格式的文章内容
• author_id（数字，必需）：作者 ID（必须是有效的 Intercom 团队成员）
• description（字符串，可选）：文章描述
• state（字符串，可选）："draft" 或 "published"（默认："draft"）
• parent_id（字符串，可选）：集合或部分 ID
• parent_type（字符串，可选）："collection"（默认）
• translated_content（对象，可选）：多语言内容

示例（简单）：

{
  "title": "Getting Started Guide",
  "body": "<p>Welcome to our platform</p>",
  "author_id": 123456,
  "state": "draft"
}

示例（多语言）：

{
  "title": "Getting Started Guide",
  "body": "<p>Welcome to our platform</p>",
  "author_id": 123456,
  "state": "published",
  "translated_content": {
    "zh-TW": {
      "title": "入門指南",
      "body": "<p>歡迎使用我們的平台</p>",
      "author_id": 123456,
      "state": "published"
    },
    "ja": {
      "title": "スタートガイド",
      "body": "<p>プラットフォームへようこそ</p>",
      "author_id": 123456,
      "state": "published"
    }
  }
}

update_article

更新现有文章。仅更新提供的字段。 参数：

• id（字符串，必需）：文章 ID
• title（字符串，可选）：更新后的标题
• body（字符串，可选）：更新后的内容
• description（字符串，可选）：更新后的描述
• state（字符串，可选）："draft" 或 "published"
• author_id（数字，可选）：更新后的作者 ID
• translated_content（对象，可选）：更新后的翻译内容

示例（更改状态）：

{
  "id": "9876543",
  "state": "published"
}

示例（更新内容）：

{
  "id": "9876543",
  "title": "Updated Title",
  "body": "<p>Updated content</p>"
}

示例（添加翻译）：

{
  "id": "9876543",
  "translated_content": {
    "zh-TW": {
      "title": "更新的標題",
      "body": "<p>更新的內容</p>"
    }
  }
}

list_collections

列出所有帮助中心集合（顶级类别）。 参数：

• page（数字，可选）：页码（默认：1）
• per_page（数字，可选）：每页集合数（默认：50，最大：150）

示例：

{
  "page": 1,
  "per_page": 50
}

get_collection

通过 ID 获取单个集合。 参数：

• id（字符串，必需）：集合 ID

示例：

{
  "id": "14608214"
}

update_collection

更新现有集合。仅更新提供的字段。非常适合添加缺失的翻译！ 参数：

• id（字符串，必需）：集合 ID
• name（字符串，可选）：更新后的集合名称（更新默认语言）
• description（字符串，可选）：更新后的描述（更新默认语言）
• parent_id（字符串，可选）：父集合 ID（顶级为 null）
• translated_content（对象，可选）：更新后的翻译内容

示例（更新名称和描述）：

{
  "id": "14608214",
  "name": "Account Management",
  "description": "Manage your account settings"
}

示例（添加缺失的日语翻译）：

{
  "id": "14608214",
  "translated_content": {
    "ja": {
      "name": "アカウント管理",
      "description": "アカウント設定を管理"
    }
  }
}

示例（更新多种语言翻译）：

{
  "id": "14608214",
  "translated_content": {
    "ja": {
      "name": "アカウント管理",
      "description": "アカウント設定を管理する"
    },
    "id": {
      "name": "Manajemen Akun",
      "description": "Kelola pengaturan akun Anda"
    }
  }
}

delete_collection

永久删除集合。警告：此操作无法撤销！ 参数：

• id（字符串，必需）：要删除的集合 ID

示例：

{
  "id": "16036040"
}

⚠️ 重要提示：

• 已删除的集合无法恢复
• 集合内的所有内容可能会受到影响
• 删除前务必备份重要数据

开发

构建

npm run build

监听模式

npm run watch

故障排除

Claude 桌面版未显示工具

1. 检查配置文件路径是否正确
2. 验证 JSON 格式（无尾随逗号）
3. 完全重启 Claude 桌面版
4. 检查 dist/index.js 的绝对路径

API 错误

1. 验证你的访问令牌是否正确
2. 确保令牌具有文章读取权限
3. 检查 Intercom API 状态

构建错误

1. 确保 TypeScript 版本 >= 5.0
2. 删除 node_modules 和 dist，然后执行：

npm install && npm run build

项目结构

intercom-mcp/
├── package.json           # 项目配置
├── tsconfig.json          # TypeScript 配置
├── src/
│   └── index.ts           # 主服务器代码
├── dist/                  # 编译输出
└── README.md             # 本文件

路线图

已完成

• ✅ 获取文章（v0.1.0）
• ✅ 列出文章（v0.1.0）
• ✅ 创建文章（v0.2.0）
• ✅ 更新文章（v0.2.0）
• ✅ 文章多语言支持（v0.2.0）
• ✅ 列出集合（v0.3.1）
• ✅ 获取集合（v0.3.1）
• ✅ 更新集合（v0.4.0）
• ✅ 删除集合（v0.4.0）
• ✅ 集合多语言支持（v0.4.0）
• ✅ 关键词匹配和高亮搜索文章（v0.5.0）
• ✅ 回复对话（v0.6.0）
• ✅ 为对话添加内部备注（v0.6.0）
• ✅ 关闭对话（v0.6.0）
• ✅ 更新工单状态和属性（v0.6.0）

计划中

• 🔜 删除文章
• 🔜 批量操作
• 🔜 更好的错误处理
• 🔜 模块化文件结构

资源

• Intercom 文章 API
• MCP TypeScript SDK
• MCP 文档

📄 许可证

本项目采用 MIT 许可证。