Help Scout Mcp Server

AI アシスタントから Help Scout の受信トレイ、会話、顧客、組織、スレッド、Docs ナレッジベースに直接アクセスできるMCP サーバーです。チケットを検索し、顧客やアカウントの情報を取得し、記事を確認して、パターンを見つけ、エディターやチャット画面を離れずに回答を得られます。

Help Scout を利用する顧客であり、サポートチームに特別な力を与えたいと考えた開発者が作成しました。Help Scout で顧客との会話に対応していて、AI の力で作業を効率化したい方に最適です。

できること

• 会話を検索：キーワード、日付範囲、ステータス、タグ、メールドメイン、チケット番号で検索できます
• 顧客を検索：名前、高度なクエリ構文、または正確なメールアドレスで検索できます
• 組織を確認：顧客や会話を直接たどることができます
• 会話の詳細を確認：チケットの生メタデータ、要約、スレッド全体、添付ファイル、元のソースを確認できます
• スレッドの履歴全体を取得：返信を作成する前に、履歴をコンテキストに取り込めます
• 会話の要約を取得：顧客からの元のメッセージと、スタッフによる最新の返信を確認できます
• Docs 記事を検索・取得：Help Scout Docs の専用 API から記事を取得できます
• Help Scout のレポートとメタデータを取得：会社、会話、Docs、チャネル、生産性、顧客満足度、ユーザー、チーム、システムユーザー、ステータス、ルーティング、Webhook に関する情報を取得できます
• 受信トレイのアクティビティを監視：1 回のクエリで複数の受信トレイを確認できます
• オプトインで操作を実行：返信の下書き、内部メモ、タグ、ステータス、割り当て、スヌーズなどを実行できます。すべてデフォルトでは無効です
• メッセージのペイロードを削減：オプションのメッセージ内容のマスキングと、受信トレイへのアクセス範囲の指定を利用できます

クイックスタート

Claude Desktop と Claude Cowork（推奨）

Desktop Extensionsを使ってワンクリックでインストールできます。1 回のインストールで、Claude デスクトップアプリのチャットセッションと 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 もサポートされています。

ナレッジベースツールは、Mailbox API とは別の Help Scout Docs API v1 を使用します。listDocs*、searchDocsArticles、getDocsArticle、またはリダイレクトツールを使う場合にのみ、HELPSCOUT_DOCS_API_KEY を設定してください。

ツール

サーバーは、サポートされているすべての読み取り操作（Mailbox API と Docs API 全体で55件）を合わせて実行できる、3つのツールを公開します。

ツール	目的
search_help_scout	「顧客との会話履歴」「顧客満足度レポート」などの意図で操作を検索します
describe_help_scout	選択した操作の入力スキーマ全体を読み込みます
read_help_scout	1つの操作を実行します：{ "name": "getThreads", "arguments": { ... } }

これにより、公開するインターフェースを小さく保ち、AI クライアントがスキーマに圧倒されるのを防ぎながら、あらゆる読み取り機能を検索ひとつで利用できるようにしています。現在のレジストリにある操作は、名前を直接指定して引き続き呼び出すこともできます。v2.0.0 の統合で削除されたツール名（例：comprehensiveConversationSearch、structuredConversationFilter、searchInboxes）は呼び出せません。それらの機能は searchConversations と listAllInboxes に含まれています。

4つ目のオプションツール write_help_scout は、運用者が書き込みを有効にした場合にのみ表示されます。書き込み操作（オプトイン）を参照してください。

MCP の互換性に関する契約とロードマップについては、以下を参照してください。

• MCP ツールの契約
• MCP と CLI の境界
• MCP ツールの公開範囲に関するロードマップ

どの操作を使えばよいですか？

read_help_scout を使って、以下のいずれかを実行します。

タスク	操作	例
最近のチケットを一覧表示する	searchConversations	"今週の対応中のチケットを表示して"
キーワードで検索する	searchConversations (contentTerms)	"請求エラーに関する会話を検索して"
チケット番号を検索する	searchConversations (conversationNumber)	"チケット #42839 を表示して"
複雑な条件で絞り込む	searchConversations (emailDomain, tag)	"urgent タグが付いた @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 エージェントには受信トレイ ID が指示に自動的に含まれるため、検索する必要はありません。

書き込み操作（オプトイン）

デフォルトのインストールは読み取り専用です。上記の 3 つのツールのみを公開し、2.0 から変更はありません。書き込み機能は、オペレーターがフラグを設定した場合にのみ有効になります。

フラグ	追加されるもの
HELPSCOUT_ENABLE_WRITES=true	4 つ目のツール write_help_scout。Tier 1 の会話操作 11 種類を提供します
HELPSCOUT_ENABLE_CUSTOMER_VISIBLE_WRITES=true	同じツールに sendReply と publishDraft の 2 つの操作を追加します

Tier 1 では、返信の下書き、内部メモ、ステータス変更、割り当てと割り当て解除、タグの追加と削除、カスタムフィールド値、スヌーズとスヌーズ解除、会話の別の受信トレイへの移動ができます。これらの操作でメールが送信されることはありません。下書きは未送信の状態で保存され、メモはチームメイトにのみ表示されます。

Tier 2 は顧客に届く唯一の方法であり、両方のフラグが必要です。sendReply または publishDraft のすべての呼び出しには、操作名と対象を指定した確認情報も含める必要があります。

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

確認情報がない、false である、または内容が一致しない場合、Help Scout に何も送信される前に拒否されます。削除と管理設定への書き込みは、どのフラグを設定しても意図的に公開されません。

Help Scout に接続せずに引数を検証し、送信されるリクエストの内容を正確に確認するには、書き込み操作に "dryRun": true を設定してください。

詳細なルール：書き込みツールの仕様。

設定

変数	説明	デフォルト
HELPSCOUT_APP_ID	Help Scout My Apps のアプリ ID	必須
HELPSCOUT_APP_SECRET	Help Scout My Apps のアプリシークレット	必須
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	tier-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 Discussions
• NPM パッケージ
• 変更履歴

ライセンス

MIT ライセンス - 詳細はLICENSEを参照してください。