Intercom Articles MCP

内部通信MCP服务器

用于帮助中心内容管理和CS工作流自动化的内部通信MCP服务器。

版本

v0.7.0 -添加了delete_article、create_collection、list_admin；优化搜索文章响应

特性

条款

• ✅ get_article -按ID获取一篇文章
• ✅ list_articles -按页码列出文章
• ✅ search_articles -按关键字搜索文章，并支持突出显示
• ✅ create_article -创建包含多语言内容的新文章
• ✅ update_article -用部分更新更新现有文章
• ✅ delete_article -永久删除文章

集合

• ✅ list_collections -列出所有帮助中心集合
• ✅ get_collection -按ID获取单个集合
• ✅ update_collection -更新收藏信息和翻译
• ✅ delete_collection -删除收藏（永久）
• ✅ create_collection -创建新的帮助中心集合

管理员

• ✅ list_admins -列出工作区管理员（用于查找有效的author_id）

CS工作流程

• ✅ reply_conversation -以管理员身份回复对话
• ✅ add_conversation_note -在对话中添加内部注释
• ✅ close_conversation -结束对话
• ✅ update_ticket_state -更新票证的状态

安装

1. 克隆存储库：

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

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

配置

获取内部通信访问令牌

1. 转到对讲机设置→ 开发者→ 开发者中心
2. 创建新应用程序或使用现有应用程序
3. 通过以下方式获取访问令牌 条款 和 对话 读写权限

环境变量

使用Claude代码配置（推荐）

如果您使用的是Claude Code CLI，则可以轻松添加MCP服务器：

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

替换：

• `` 使用您的对讲机接入令牌
• /ABSOLUTE/PATH/TO/ 使用您的实际项目路径

要验证是否已配置：

claude mcp list

手动配置Claude桌面

或者，编辑您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %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 使用您的对讲机管理员ID（CS工具需要）

重新启动克劳德桌面

完全退出Claude Desktop并重新启动。

用法

配置后，您可以在Claude Desktop中使用这些命令：

列出文章

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 （字符串，可选）：按文章状态筛选-“已发布”、“草稿”或“全部”（默认值：“全部”）
• help_center_id （字符串，可选）：按特定帮助中心ID筛选

示例（按关键字搜索）：

{
  "phrase": "subscription"
}

示例（列出所有草稿，不需要关键字）：

{
  "state": "draft"
}

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

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

答复包括：

• total_count：匹配文章总数
• articles：每篇文章的摘要字段数组（id、标题、描述、状态、url、author_id、created_at、updated_at、parent_id、parent_type）

使用 get_article 获取特定文章的全部内容。

使用案例：

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

create_article

创建具有多语言支持的新文章。

参数：

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

示例（简单）：

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

示例（多语言）：

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

update_article

更新现有文章。只有提供的字段才会更新。

参数：

• id （字符串，必填）：文章ID
• title （字符串，可选）：更新标题
• body （字符串，可选）：更新内容
• description （字符串，可选）：更新的描述
• state （字符串，可选）：“草稿”或“已发布”
• author_id （数字，可选）：更新的作者ID
• translated_content （对象，可选）：更新的翻译

示例（更改状态）：

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

示例（更新内容）：

{
  "id": "9876543",
  "title": "Updated Title",
  "body": "
Updated content
"
}

示例（添加翻译）：

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

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"
}

⚠️ 重要提示：

• 已删除的收藏无法恢复
• 收藏中的所有内容都可能受到影响
• 删除前始终备份重要数据

delete_article

永久删除一篇文章。 警告：此操作无法撤消！

参数：

• id （字符串，必填）：要删除的文章ID

例子：

{
  "id": "9876543"
}

create_collection

创建新的帮助中心集合。

参数：

• name （字符串，必填）：集合名称
• description （字符串，可选）：集合描述
• parent_id （字符串，可选）：嵌套的父集合ID（顶级省略）
• translated_content （对象，可选）：按区域设置代码显示多语言内容

示例（简单）：

{
  "name": "Getting Started"
}

示例（带翻译）：

{
  "name": "Getting Started",
  "translated_content": {
    "zh-TW": {
      "name": "入門指南",
      "description": "開始使用我們的平台"
    }
  }
}

list_admins

列出所有工作区管理员。有助于查找有效 author_id 创建或更新文章时的值。

参数： 无

答复包括：

• id：管理员ID（将其用作 author_id)
• name：显示名称
• email：电子邮件地址
• has_inbox_seat：管理员是否有收件箱席位

reply_conversation

以管理员身份回复对话。客户可以看到回复。

参数：

• conversation_id （string，必填）：要回复的对话ID
• body （string，必填）：回复消息正文（支持HTML）
• admin_id （字符串，可选）：要回复的管理员ID（默认为 INTERCOM_ADMIN_ID 任何人）

例子：

{
  "conversation_id": "12345678",
  "body": "
Thank you for reaching out. We'll look into this right away.
"
}

add_conversation_note

在对话中添加内部注释。注释仅对团队成员可见，对客户不可见。

参数：

• conversation_id （string，必填）：要添加注释的对话ID
• body （string，必填）：备注内容（支持HTML）
• admin_id （字符串，可选）：添加注释的管理员ID（默认为 INTERCOM_ADMIN_ID 任何人）

例子：

{
  "conversation_id": "12345678",
  "body": "
Customer has been refunded. Follow up in 3 days.
"
}

close_conversation

结束对话。

参数：

• conversation_id （string，必填）：要关闭的对话ID

例子：

{
  "conversation_id": "12345678"
}

update_ticket_state

更新票证的状态。

参数：

• ticket_id （字符串，必填）：要更新的票证ID
• state （string，必填）：新票证状态--其中之一 in_progress, waiting_on_customer, resolved

例子：

{
  "ticket_id": "87654321",
  "state": "resolved"
}

发展

构建

npm run build

观看模式

npm run watch

故障排除

Claude Desktop未显示工具

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

API错误

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

构建错误

1. 确保TypeScript版本>=5.0
2. 删除 node_modules 和 dist那么：

npm install && npm run build

项目结构

intercom-mcp/
├── package.json           # Project configuration
├── tsconfig.json          # TypeScript configuration
├── src/
│   └── index.ts           # Main server code
├── dist/                  # Compiled output
└── README.md             # This file

路线图

完成

• ✅ 获取文章（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）
• ✅ 删除文章（v0.7.0）
• ✅ 创建集合（v0.7.0）
• ✅ 列表管理员（v0.7.0）
• ✅ 优化搜索_文章响应（v0.7.0）

计划的

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

资源

• 内部通信文章API
• MCP TypeScript SDK
• MCP文件

许可证

麻省理工学院