Intercom Articles MCP

🚀 Intercom MCP Server

Intercom MCPサーバーは、ヘルプセンターのコンテンツ管理とカスタマーサポート（CS）のワークフロー自動化を行うためのものです。

🚀 クイックスタート

Intercom MCPサーバーを使用することで、ヘルプセンターのコンテンツ管理とCSワークフローの自動化を行うことができます。以下の手順でセットアップしてください。

✨ 主な機能

記事関連

• ✅ 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 - チケットの状態や属性を更新します。

📦 インストール

1. リポジトリをクローンします：

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

2. 依存関係をインストールします：

npm install

3. プロジェクトをビルドします：

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 Desktopの手動設定

あるいは、Claude Desktopの設定ファイルを編集することもできます： 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 Desktopの再起動

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の主要な機能の1つは、多言語コレクションを効率的に管理する能力です。

欠落している翻訳の追加

特定の言語が欠落しているコレクションに翻訳を簡単に追加できます：

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

一括翻訳の更新

どのコレクションが翻訳を欠いているかを確認します：

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

その後、1つずつ更新するか、複数のコレクションを更新する計画を立てます。

翻訳の検証

更新後、変更を検証します：

Get collection 14608214 and show me all available translations

🔧 技術詳細

get_article

IDで単一の記事を取得します。 パラメータ:

• id (文字列, 必須): 記事ID

例:

{
  "id": "9876543"
}

list_articles

ページネーション付きで記事を一覧表示します。 パラメータ:

• page (数値, オプション): ページ番号 (デフォルト: 1)
• per_page (数値, オプション): 1ページあたりの記事数 (デフォルト: 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 (数値, オプション): 1ページあたりのコレクション数 (デフォルト: 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 Desktopがツールを表示しない場合

1. 設定ファイルのパスが正しいことを確認します。
2. JSON形式が正しいことを確認します（末尾のカンマはないこと）。
3. Claude Desktopを完全に再起動します。
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 Articles API
• MCP TypeScript SDK
• MCP Documentation

📄 ライセンス

MIT