Help Scout Mcp Server

一个 MCP 服务，可让 AI 助手直接访问你的 Help Scout 收件箱、会话、客户、组织、讨论串和 Docs 知识库。搜索工单、获取客户和账户背景信息、查看文章、发现规律，并在不离开编辑器或聊天窗口的情况下获得答案。

由一位 Help Scout 客户构建，他希望让支持团队如虎添翼。如果你在 Help Scout 中处理客户对话，并希望 AI 帮助你更快地工作，那么这正适合你。

你可以做什么

• 搜索会话，支持按关键词、日期范围、状态、标签、电子邮件域名或工单编号搜索
• 查找客户，支持按姓名、高级查询语法或精确电子邮件地址查找
• 浏览组织，直接遍历客户和会话
• 查看会话详情，包括原始工单元数据、摘要、完整讨论串、附件和原始来源
• 获取完整讨论串历史记录，在起草回复前将其纳入上下文
• 获取会话摘要，包括客户原始消息和员工最新回复
• 搜索并检索 Docs 文章，来自独立的 Help Scout Docs API
• 获取 Help Scout 报告和元数据，涵盖公司、会话、Docs、渠道、生产力、满意度、用户、团队、系统用户、状态、路由和 Webhook
• 监控收件箱活动，通过单次查询查看多个收件箱
• 通过可选写入执行操作：起草回复、添加内部备注、标签、状态、分配、暂停等；默认全部关闭
• 缩减消息载荷，支持可选的消息内容编辑和限定收件箱访问范围

快速开始

Claude Desktop 和 Claude Cowork（推荐）

使用 Desktop Extensions 一键安装。一次安装即可用于 Claude 桌面应用中的 Chat 和 Cowork 会话。

1. 下载最新的发布版 .mcpb 文件
2. 双击安装（或将文件拖入 Claude Desktop）
3. 在扩展设置中输入 Help Scout App ID 和 App Secret；设置中还包含消息编辑和可选写入功能的开关
4. 重启 Claude Desktop

如果工具没有出现在 Cowork 会话中，请将桌面应用更新到最新版本并启动一个新会话。（Cowork 操作指南）

可选：添加 helpscout-navigator 技能，让 Claude 更快地选择正确操作。前往 Customize，点击 + > Add marketplace from GitHub，输入 drewburchfield/help-scout-mcp-server，然后安装 helpscout-navigator。

Claude Code

注册服务，然后可选择添加 helpscout-navigator 技能，它会教 Claude 根据每个查询选择正确的操作。

claude mcp add helpscout \
  --env HELPSCOUT_APP_ID=your-app-id \
  --env HELPSCOUT_APP_SECRET=your-app-secret \
  -- npx -y help-scout-mcp-server

然后，安装导航技能：

1. 运行 /plugin marketplace add drewburchfield/help-scout-mcp-server
2. 运行 /plugin install helpscout-navigator

服务本身提供工具；该技能还会教 AI 如何善用这些工具。

适用于 Cursor、VS Code 和其他 MCP 客户端

将以下内容添加到 MCP 客户端的配置文件中（例如 claude_desktop_config.json、.cursor/mcp.json）：

{
  "mcpServers": {
    "helpscout": {
      "command": "npx",
      "args": ["[email protected]"],
      "env": {
        "HELPSCOUT_APP_ID": "your-app-id",
        "HELPSCOUT_APP_SECRET": "your-app-secret",
        "HELPSCOUT_DOCS_API_KEY": "optional-docs-api-key"
      }
    }
  }
}

Docker

docker run -e HELPSCOUT_APP_ID="your-app-id" \
  -e HELPSCOUT_APP_SECRET="your-app-secret" \
  -e HELPSCOUT_DOCS_API_KEY="optional-docs-api-key" \
  drewburchfield/help-scout-mcp-server:2.1.0

获取 API 凭据

1. 前往 Help Scout > My Apps > Create Private App
2. 复制你的 App ID 和 App Secret

Help Scout 仅使用 OAuth2 客户端凭据流。不支持个人访问令牌。应用会以创建它的用户身份进行身份验证，并拥有该用户的权限；没有单独的范围选择，这也是服务端默认关闭自身写入控制的原因。

Help Scout UI	环境变量
App ID	HELPSCOUT_APP_ID
App Secret	HELPSCOUT_APP_SECRET

也支持替代名称 HELPSCOUT_CLIENT_ID / HELPSCOUT_CLIENT_SECRET。

Docs 知识库工具使用独立于 Mailbox API 的 Help Scout Docs API v1。只有在要使用 listDocs*、searchDocsArticles、getDocsArticle 或重定向工具时，才设置 HELPSCOUT_DOCS_API_KEY。

工具

此服务会公布三个工具，它们共同覆盖所有受支持的读取操作（Mailbox 和 Docs API 中共 55 项）：

工具	用途
search_help_scout	按意图查找操作（“客户对话历史记录”“满意度报告”）
describe_help_scout	加载所选操作的完整输入架构
read_help_scout	执行一项操作：{ "name": "getThreads", "arguments": { ... } }

这样公布的工具范围足够精简，不会让 AI 客户端被架构淹没，同时所有读取功能都能通过一次搜索找到。当前注册表中的操作也仍可直接按名称调用。v2.0.0 整合中移除的工具名称（例如 comprehensiveConversationSearch、structuredConversationFilter 和 searchInboxes）则不可调用；它们的功能已包含在 searchConversations 和 listAllInboxes 中。

只有在操作员启用写入后，才会显示可选的第四个工具 write_help_scout。请参阅写入操作（选择启用）。

有关 MCP 兼容性规范和路线图，请参阅：

• MCP 工具规范
• MCP 与 CLI 的边界
• MCP 工具范围路线图

应该使用哪个操作？

通过 read_help_scout 运行以下任一操作：

任务	操作	示例
列出近期工单	searchConversations	"显示本周的活跃工单"
按关键词查找	searchConversations (contentTerms)	"查找有关账单错误的对话"
查找工单编号	searchConversations (conversationNumber)	"显示工单 #42839"
使用复杂筛选条件	searchConversations (emailDomain, tag)	"列出所有标记为紧急的 @acme.com 对话"
浏览客户	listCustomers	"显示名为 Jane 的客户"
按电子邮件查找客户	searchCustomersByEmail	"查找客户 [email protected]"
查看客户资料	getCustomer	"打开客户 12345"
获取客户的联系渠道	getCustomerContacts	"显示客户 12345 的联系详情"
浏览组织	listOrganizations	"显示最繁忙的组织"
查看组织	getOrganization	"打开组织 456"
列出组织中的客户	getOrganizationMembers	"谁属于组织 456？"
列出组织的对话	getOrganizationConversations	"显示组织 456 的支持记录"
查看原始对话详情	getConversation	"打开对话 12345，查看完整元数据"
快速查看对话概况	getConversationSummary	"总结此对话"
查看完整消息历史记录	getThreads	"显示完整对话线程"
查看收件箱字段、文件夹或路由	getInbox (include)	"显示收件箱 359402 的路由" (include: ["routing"])
搜索 Docs 文章	searchDocsArticles	"查找有关退款的知识库文章"
获取 Docs 文章	getDocsArticle	"打开 Docs 文章 123"
当前 MCP 主机时间	getServerTime	用于基于时间的搜索

服务器连接时会自动发现收件箱。AI Agent 的指令中会自动包含收件箱 ID，因此无需查找。

写入操作（选择启用）

默认安装为只读模式。它会公布上述三个工具，不提供其他工具，与 2.0 保持不变。只有在操作员设置标志后，才会启用写入操作。

标志	添加的内容
HELPSCOUT_ENABLE_WRITES=true	第四个工具 write_help_scout，包含 11 个一级对话操作
HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES=true	在同一工具中再添加两个操作：sendReply 和 publishDraft

一级操作包括草稿回复、内部备注、状态更改、分配和取消分配、添加和移除标签、自定义字段值、暂停和取消暂停，以及将对话移至其他收件箱。这些操作都不会向任何人发送电子邮件：草稿会保存但不会发送，备注仅团队成员可见。

二级操作是唯一会触达客户的途径，并且需要同时启用两个标志。每次调用 sendReply 或 publishDraft 时，还必须附带确认信息，说明操作名称和目标：

{
  "name": "sendReply",
  "arguments": { "conversationId": "12345", "text": "..." },
  "confirm": true,
  "confirmOperation": "sendReply",
  "targetId": "12345"
}

如果缺少确认信息、确认信息为 false 或与实际操作不匹配，系统会拒绝请求，不会将任何内容发送给 Help Scout。无论设置什么标志，都不会开放删除操作和管理配置写入操作。

对任何写入操作设置 "dryRun": true，即可验证参数并查看将要发送的确切请求，而不会联系 Help Scout。

完整规则：写入工具契约。

配置

变量	描述	默认值
HELPSCOUT_APP_ID	Help Scout My Apps 中的 App ID	必填
HELPSCOUT_APP_SECRET	Help Scout My Apps 中的 App Secret	必填
HELPSCOUT_DEFAULT_INBOX_ID	将搜索范围限定为特定收件箱	无（所有收件箱）
HELPSCOUT_BASE_URL	Help Scout API 端点	https://api.helpscout.net/v2/
HELPSCOUT_DOCS_API_KEY	知识库工具可选的 Docs API 密钥	无
HELPSCOUT_DOCS_BASE_URL	Help Scout Docs API 端点	https://docsapi.helpscout.net/v1/
REDACT_MESSAGE_CONTENT	将消息正文替换为占位符	false
HELPSCOUT_ENABLE_WRITES	使用第 1 层会话写入功能启用 write_help_scout	未设置（false）
HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES	同时启用会向客户发送邮件的 sendReply 和 publishDraft	未设置（false）
CACHE_TTL_SECONDS	API 响应的缓存时长	300
LOG_LEVEL	日志详细程度（error、warn、info、debug）	info

兼容性

适用于任何 MCP 兼容客户端：

类别	客户端
AI 助手	Claude Desktop（Chat 和 Cowork）、Goose 及其他启用 MCP 的助手
代码编辑器	Cursor、VS Code、Windsurf、Continue.dev
命令行	Claude Code、Codex、Gemini CLI、OpenCode
自定义	任何实现 MCP 标准的应用程序

安全与隐私

专为注重安全的团队打造：

• 可选的消息内容脱敏。 默认会包含消息正文。设置 REDACT_MESSAGE_CONTENT=true，可将会话和线程正文替换为占位符，以便进行上下文较少的分析。这并非合规边界，也不会移除所有客户标识信息。
• 安全身份验证。 使用 OAuth2 客户端凭据，并自动刷新令牌。
• 速率限制处理。 收到 429 响应时自动以指数退避方式重试。
• 限定访问范围。 可选的默认收件箱配置可限制 AI 的搜索范围。

故障排除

身份验证失败？ 请验证凭据能否直接用于 Help Scout：

curl -X POST https://api.helpscout.net/v2/oauth2/token \
  -d "grant_type=client_credentials&client_id=$HELPSCOUT_APP_ID&client_secret=$HELPSCOUT_APP_SECRET"

搜索结果为空？ 常见原因：

• 忘记 searchConversations 是唯一的搜索工具：使用 contentTerms/subjectTerms 进行关键词搜索，使用普通筛选条件列出内容
• 收件箱 ID 不匹配。请查看服务说明中的 ID，不要猜测。
• 搜索词范围过窄。尝试更宽泛的词语或更长的时间范围。

需要更多详细信息？ 启用调试日志：

LOG_LEVEL=debug npx [email protected]

开发

git clone https://github.com/drewburchfield/help-scout-mcp-server.git
cd help-scout-mcp-server
npm install && npm run build
npm start

npm test           # Run tests
npm run type-check # TypeScript validation
npm run lint       # Linting
npm run dev        # Development server with auto-reload

欢迎贡献。提交 PR 前，请确保测试、类型检查和代码检查均已通过。

支持

• GitHub 问题
• GitHub 讨论
• NPM 软件包
• 更新日志

许可证

MIT 许可证——详情请参阅 LICENSE。