AI导哈

HelpScout命令行工具

一个用于HelpScout的命令行工具，覆盖Mailbox API v2和Docs API v1，设计用于脚本编写、自动化和AI代理使用。

  • by mobilelocker
  • JavaScript
  • 本地部署
  • 更新于
在 GitHub 查看 mobilelocker/helpscout-cli

使用说明

helpscout命令行界面

一个命令行工具 帮助童子军，涵盖邮箱API v2（对话、客户、用户）和完整的文档API v1（文章、收藏、类别、重定向、网站、资产）。

专为AI代理的脚本编写、自动化和使用而设计。附带MCP服务器(helpscout-mcp)用于与Claude Code、Claude Desktop和Cursor直接集成。默认情况下，当不在终端时输出JSON，当在终端时则输出漂亮的表。

先决条件

  • Node.js 20或更高版本
  • Help Scout帐户：
    • OAuth应用程序（用于邮箱API）-在创建一个 您的个人资料→ 我的应用程序
    • API密钥（用于Docs API）-在 您的个人资料→ API密钥

安装

git clone https://github.com/mobilelocker/helpscout-cli.git helpscout-cli
cd helpscout-cli
./install.sh

install.sh 跑 npm install，生成两个二进制文件(helpscout 和 helpscout-mcp)，将它们复制到 /usr/local/bin，停止任何已运行的 helpscout-mcp 进程（这样升级后就不会保留旧的内存服务器），并使用Claude Code和Cursor（检测到时）注册MCP服务器——所有这些都在一个步骤中完成。如果编辑器已连接Help Scout MCP，请重新连接它（或打开一个新会话），以便它启动新的二进制文件。

开发（从源代码运行）

git clone https://github.com/mobilelocker/helpscout-cli.git helpscout-cli
cd helpscout-cli
npm install
node bin/helpscout.js <command>

配置

CLI从环境变量中读取凭据。将这些添加到您的shell配置文件或机密管理器中：

# Required for Mailbox API (conversations, customers, users, etc.)
export HELPSCOUT_APP_ID="your-oauth-app-id"
export HELPSCOUT_APP_SECRET="your-oauth-app-secret"

# Required for Docs API (articles, collections)
export HELPSCOUT_API_KEY="your-api-key"

认证

邮箱API使用OAuth 2.0。验证一次，令牌将缓存48小时（自动刷新）：

helpscout auth login     # opens browser, follow the prompt
helpscout auth status    # check when your token expires
helpscout auth logout    # remove the cached token

API文档使用您的 HELPSCOUT_API_KEY directly--无需登录步骤。

MCP 服务器

helpscout-mcp 是一个 主控程序 该服务器将所有Help Scout操作公开为与Claude Code、Claude Desktop和Cursor一起使用的工具。

运行后 install.sh，它会自动注册到Claude Code（用户范围）和Cursor中(~/.cursor/mcp.json)当检测到这些编辑器时。要将其添加到特定项目中，请执行以下操作：

{
  "mcpServers": {
    "helpscout": {
      "command": "/usr/local/bin/helpscout-mcp"
    }
  }
}

MCP服务器包括 auth_login 该工具按需打开浏览器OAuth流，因此代理可以在不离开对话的情况下处理身份验证。

文档文章工具支持完整的API字段，包括 categories, related，以及 keywords 阵列打开 create_article 和 update_article （不需要原始HTTP/cURL）。更新时，省略 categories 保持不变，通过 null 或 clearCategories: true 移动到“未分类”，或传递要替换的类别ID数组。

对于长HTML/文本体，更喜欢文件而不是内联文本：MCP filePath （绝对路径）或CLI --file <path>。提供内联字段(text/body/--text/--body)或 filePath/--file不是两者都有。适用于文档文章创建/更新/草稿和收件箱回复/注释/对话创建。文章创建/更新仍然使用JSON API（与multipart不同 upload_article).

输出格式

默认情况下，CLI检测它是否在终端中运行：

  • 终端：漂亮的彩色桌子
  • 管道/脚本：JSON

用每个命令上可用的标志覆盖：

helpscout inbox mailbox list              # table in terminal, JSON in pipe
helpscout inbox mailbox list --json       # always JSON
helpscout inbox mailbox list --pretty     # always table
helpscout inbox mailbox list --markdown   # always Markdown table (GFM)

错误总是以JSON格式写入stderr，并以代码1退出：

{ "error": "Not authenticated. Run: helpscout auth login" }

用法

对话

# List active conversations
helpscout inbox conversation list --mailbox <mailbox-id>

# All pages, closed conversations, filtered by tag
helpscout inbox conversation list --status closed --tag billing --all

# Get a single conversation
helpscout inbox conversation get <id>

# Create a conversation
helpscout inbox conversation create \
  --subject "Welcome!" \
  --mailbox-id <mailbox-id> \
  --customer-email user@example.com \
  --body "<p>Thanks for signing up.</p>"
# or: --file ./welcome.html

# Reply and add an internal note
helpscout inbox thread reply <id> --text "<p>We're looking into this.</p>"
helpscout inbox thread reply <id> --file ./reply.html
helpscout inbox thread note <id> --text "<p>Escalated to engineering.</p>"
helpscout inbox thread note <id> --file ./note.html

# Close a conversation
helpscout inbox conversation update <id> --status closed

客户

helpscout inbox customer list --email user@example.com
helpscout inbox customer get <id>
helpscout inbox customer create --email new@example.com --first-name Jane --last-name Doe
helpscout inbox customer update <id> --phone "+15555550100"

用户和邮箱

helpscout inbox user me                        # who am I?
helpscout inbox user list                      # all users
helpscout inbox mailbox list                   # all mailboxes with their IDs

helpscout inbox user status get <id>           # email + chat status for a user
helpscout inbox user status list               # statuses for all users
helpscout inbox user status set <id> --status active --text "On a call" --emoji 📞

标签

helpscout inbox tag list

Webhooks

helpscout inbox webhook list
helpscout inbox webhook create \
  --url https://example.com/hook \
  --secret mysecret \
  --events convo.created,convo.assigned \
  --payload-version v3   # opt into V3 payloads (preserves system_user type)
helpscout inbox webhook delete <id>

文档文章

# List articles in a collection (default status: all)
helpscout docs article list --collection <collection-id> --all

# Search
helpscout docs article search --query "getting started" --site <site-id>

# Create with one or more categories (repeat --category for each id)
helpscout docs article create \
  --collection <collection-id> \
  --name "New Feature Guide" \
  --text "<p>Content here.</p>" \
  --category <category-id> \
  --category <other-category-id> \
  --keyword "feature" \
  --reload

# Create / update / draft body from a file (alternative to --text)
helpscout docs article create --collection <collection-id> --name "Guide" --file ./body.html
helpscout docs article update <id> --file ./body.html
helpscout docs article save-draft <id> --file ./draft.html

# Update categories: assign, leave unchanged, or move to Uncategorized
helpscout docs article update <id> --status published
helpscout docs article update <id> --category cat-a --category cat-b   # replace category list
helpscout docs article update <id> --clear-categories                  # null → Uncategorized

helpscout docs article delete <id>

MCP(create_article / update_article / save_article_draft): 过 categories 作为字符串数组，例如。 "categories": ["<category-id>"]。更新时，省略该字段以保持类别不变；使用 "categories": null 或 "clearCategories": true 未分类。对于正文HTML，请传递 text 或 filePath （磁盘上的绝对路径）。相同 filePath 收件箱上的图案 reply_to_conversation, add_note，以及 create_conversation (body 或 filePath).

文档集合、类别、重定向、网站

helpscout docs collection list
helpscout docs collection create --site <site-id> --name "FAQ"

helpscout docs category list --collection <collection-id>
helpscout docs category create --collection <id> --name "Getting Started"

helpscout docs redirect list --site <site-id>
helpscout docs redirect create --site <id> --url-mapping /old --redirect https://example.com/new

helpscout docs site create --title "Docs" --subdomain docs --bg-color "#444444" --has-contact-form
helpscout docs site restrictions update <site-id> --enabled --authentication CALLBACK --sign-in-url https://example.com/signin

文档资产

helpscout docs asset create-article --file ./screenshot.png
helpscout docs asset create-settings --file ./logo.png

发展

npm test              # unit tests (offline; no live Help Scout calls)
npm run test:integration  # live API tests (requires HELPSCOUT_* credentials)
npm run scrape:docs-api  # refresh docs/docs-api-endpoints.json from Help Scout docs
npm run lint          # check for lint errors
npm run lint:fix  # auto-fix lint errors
npm run format    # format with Prettier
npm run build     # bundle to dist/helpscout and dist/helpscout-mcp

预提交钩子在暂存文件上自动运行ESLint和Prettier。

作者

建造于 移动储物柜 — support@mobilelocker.com

Mobile Locker是生命科学行业的内容管理和参与平台。我们帮助制药、医疗器械和诊断公司向医疗保健专业人员提供个性化内容，包括页面分析、CRM集成（Salesforce、Veeva）和为监管环境构建的人工智能建议。

许可证

麻省理工学院

相关 MCP