Zendesk

@mindstone/mcp-server-zendesk

Zendesk Support MCP サーバー — 標準的な stdio MCP パッケージを通じて、チケット、ユーザー、コメント、マクロ、アカウント設定、サポートワークフローの検出を行います。

ローカルの MCP ホストからアシスタントに Zendesk チケットのトリアージ、要約、更新を行わせたいサポートチームに最適です。

ステータス

• バージョン： 0.4.1 · npm
• 認証： ハイブリッド（API トークンまたは OAuth）（ZENDESK_CLIENT_SECRET）
• ツール： 26（チケット、ユーザー、コメント、マクロ、ビュー、ヘルプセンター、顧客満足度）
• サーフェス： cloud-api
• 機械可読： STATUS.json

このパッケージについて

Zendesk は、プラットフォーム全体との統合を広げるため、独自の MCP クライアントおよびサーバー機能を発表しています。このパッケージは、ローカルの Zendesk Support コネクターをインストールして直接実行したい MCP ホスト向けです。

人が通常依頼するサポート業務をアシスタントが行えるようにします。緊急のチケットを見つけ、最新の状況を取得し、コメントを作成または追加し、マクロを適用し、ユーザーや組織を検索し、サポート設定を確認できます。その利点は、チケットのトリアージとフォローアップを迅速化しながら、顧客が作成したチケットのテキストを従うべき指示ではなく、引用・要約の対象として扱えることです。

対話例

「優先度の高い未解決の Zendesk チケットを探し、最初のチケットの最新情報を表示してください。」

ホストが呼び出すツール：

1. search_zendesk_tickets — type:ticket status:open priority:high を検索し、チケットの概要を返します。
2. get_zendesk_ticket — 選択したチケットを取得します。折り返し表示された件名と説明文も含まれます。

応答（抜粋）：

{
  "ok": true,
  "ticket": {
    "id": 12345,
    "status": "open",
    "priority": "high",
    "subject": "<untrusted-content source=\"external-ticket\">Login issue</untrusted-content>",
    "description": "<untrusted-content source=\"external-ticket\">Customer cannot access the admin dashboard.</untrusted-content>"
  }
}

要件

• Node.js 20+
• npm

ワンクリックインストール

ボタンをクリックすると、ホストから次の項目を入力するよう求められます：ZENDESK_CONFIG_PATH、ZENDESK_CLIENT_SECRET。

{
  "mcpServers": {
    "Zendesk": {
      "command": "npx",
      "args": [
        "-y",
        "@mindstone/mcp-server-zendesk"
      ],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk",
        "ZENDESK_CLIENT_SECRET": ""
      }
    }
  }
}

クイックスタート

インストールとビルド

cd <path-to-repo>/connectors/zendesk
npm install
npm run build

npx（公開後）

npx -y @mindstone/mcp-server-zendesk

ローカル

node dist/index.js

設定

環境変数

• ZENDESK_CONFIG_PATH — accounts.json と credentials/ を含む設定ディレクトリへのパス
• ZENDESK_CLIENT_ID — トークンファイルに独自の client_id がないサインインを更新する際に使用する OAuth クライアント ID。リフレッシュ時に読み込まれます
• ZENDESK_CLIENT_SECRET — 機密 OAuth クライアントでのみ使用し、ZENDESK_CLIENT_ID と併せて送信します。パブリック（PKCE）クライアントには不要です
• MCP_HOST_BRIDGE_STATE — 認証情報の管理に使用するホストブリッジの状態ファイルへの任意のパス
• MINDSTONE_REBEL_BRIDGE_STATE — MCP_HOST_BRIDGE_STATE と後方互換性のあるエイリアス

認証

各アカウントでは、2種類の認証情報のいずれかを使用します。同じサブドメインでは、API トークンより OAuth サインインが優先されます。

OAuth サインイン（推奨）。 ホストアプリが Zendesk サインイン（PKCE を使用する認可コードフローなど）を実行し、その結果を ZENDESK_CONFIG_PATH 配下の credentials/<subdomain>.token.json に、所有者のみが読み書きできる権限（0600）で書き込みます。

{
  "access_token": "…",
  "refresh_token": "…",
  "expires_in": 1800,
  "expires_at": 1767225600000,
  "token_type": "bearer",
  "subdomain": "acme",
  "email": "[email protected]",
  "client_id": "your-oauth-client-id",
  "scope": "read write"
}

expires_at はミリ秒単位のタイムスタンプです。client_id と scope は任意です。指定されている場合、トークンの更新にはそのクライアントが使用され、同じスコープが要求されます。

コネクターは、有効期限の5分前以降、または401エラー発生後に、アクセストークンを独自に更新します。

• リフレッシュトークンとクライアント ID（トークンファイルの client_id、なければ ZENDESK_CLIENT_ID）を含む JSON リクエストを https://<subdomain>.zendesk.com/oauth/tokens に送信します。パブリッククライアントにはクライアントシークレットは不要です。
• 複数のツール呼び出しが同時に発生した場合も、トークンの更新は1回だけ行われます。また、最初にトークンファイルを再読み込みするため、別のプロセスで更新されたトークンが再使用されずに使われます。
• ローテーションされたリフレッシュトークンは、ファイルをアトミックに置き換えて保存します。ただし、ファイルに、直前に使用したリフレッシュトークンがまだ記録されている場合に限ります。更新中にトークンファイルが削除された場合（アカウントが切断された場合）は再作成されません。新しいサインインによって置き換えられた場合は、そのファイルが保持され、代わりに使用されます。
• 更新したトークンを保存できない場合（ディスクの容量不足または読み取り専用など）、コネクターはメモリ上でそのトークンを使い続け、使用済みのリフレッシュトークンを再送信しません。list_zendesk_accounts は、ファイルに変更があるまで、そのアカウントに warning を表示します。再起動後は、アカウントへの再サインインが必要になることがあります。
• Zendesk がリフレッシュトークンを拒否した場合（invalid_grant、invalid_client、unauthorized_client）、またはクライアント ID がない場合、ツール呼び出しは AUTH_FAILED と「Reconnect Zendesk…」を返し、list_zendesk_accounts は reconnect-required を報告します。トークンファイルは保持されます。再度サインインすると置き換えられます。
• 一時的なエラー（サーバーエラー、レート制限、ネットワークエラー）が発生した場合、アクセストークンの有効期限が切れた後は AUTH_REFRESH_FAILED（「しばらくしてから再試行してください」）を返します。次の呼び出しで再試行されます。

API トークン。 accounts.json（下記を参照）に subdomain、email、apiToken を含むエントリーを作成し、HTTP Basic 認証として送信します。API トークンには有効期限がないため、常に active です。

スタンドアロン設定ディレクトリ

API トークンを使用するには、設定ディレクトリと accounts.json ファイルを作成します。

mkdir -p ~/.mcp/zendesk
cat > ~/.mcp/zendesk/accounts.json <<'EOF'
{
  "accounts": [
    {
      "subdomain": "yourcompany",
      "email": "[email protected]",
      "apiToken": "your-zendesk-api-token"
    }
  ],
  "defaultSubdomain": "yourcompany"
}
EOF

ホスト設定の例

Claude Desktop / Cursor

{
  "mcpServers": {
    "Zendesk": {
      "command": "npx",
      "args": ["-y", "@mindstone/mcp-server-zendesk"],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
      }
    }
  }
}

ローカル開発（npm への公開は不要）

{
  "mcpServers": {
    "Zendesk": {
      "command": "node",
      "args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
      "env": {
        "ZENDESK_CONFIG_PATH": "~/.mcp/zendesk"
      }
    }
  }
}

Mindstone Rebel

"Zendesk": {
  "name": "Zendesk",
  "type": "stdio",
  "command": "node",
  "args": ["<path-to-repo>/connectors/zendesk/dist/index.js"],
  "env": {
    "ZENDESK_CONFIG_PATH": "~/Library/Application Support/mindstone-rebel/mcp/zendesk",
    "MCP_HOST_BRIDGE_STATE": "~/Library/Application Support/mindstone-rebel/mcp/rebel-inbox-bridge.json"
  },
  "description": "Zendesk support tickets...",
  "catalogId": "bundled-zendesk"
}

ツール（26）

アカウント管理

• list_zendesk_accounts — 接続済みアカウントと認証状態を一覧表示します
• remove_zendesk_account — Zendesk アカウントの接続を解除します
• authenticate_zendesk_account — API トークンを使用して接続します

チケット

• search_zendesk_tickets — Zendesk クエリー構文を使用して検索します（結果は最大1000件）
• export_zendesk_tickets — カーソルベースでエクスポートします。結果数に1000件の上限はありません
• get_zendesk_ticket — ID を指定して単一のチケットを取得します
• get_zendesk_tickets_by_ids — 複数のチケットを一括取得します
• create_zendesk_ticket — 新しいチケットを作成します
• update_zendesk_ticket — チケットのフィールドやステータスを更新するか、コメントを追加します

ユーザー

• search_zendesk_users — 名前、メールアドレス、またはクエリーで検索します
• get_zendesk_user — ID を指定してユーザーを取得します
• create_or_update_zendesk_user — ユーザーを作成するか、同じメールアドレスを持つユーザーを更新します

コメント

• list_zendesk_ticket_comments — 作成者を解決して会話スレッドを一覧表示
• add_zendesk_ticket_comment — 公開返信または内部メモを追加

検索

• list_zendesk_groups — エージェントグループを一覧表示
• list_zendesk_ticket_fields — カスタムフィールドを含むチケットフィールドを一覧表示
• list_zendesk_views — 保存済みチケットビューを一覧表示
• list_zendesk_view_tickets — ビューを実行してチケットを一覧表示
• list_zendesk_organizations — 組織を一覧表示
• get_zendesk_organization — IDで単一の組織を取得

マクロ

• list_zendesk_macros — マクロを一覧表示または検索
• get_zendesk_macro — マクロの詳細を取得
• apply_zendesk_macro — チケットへのマクロの適用をプレビューして実行

ヘルプセンター

• search_zendesk_help_center_articles — ナレッジベースの記事を検索
• get_zendesk_help_center_article — ヘルプセンターの記事全文を読む

満足度

• list_zendesk_satisfaction_ratings — 評価スコアや日付で絞り込んでCSAT評価を一覧表示

セキュリティに関する注意事項

• Zendesk APIトークンの認証情報はaccounts.jsonに保存されます。OAuth認証情報は、ZENDESK_CONFIG_PATH配下のcredentials/*.token.jsonから読み取られます。更新されたトークンは同じフォルダー内のアクセス権限0600の一時ファイルに書き込まれ、その後、元の場所に名前を変更して配置されます。更新に失敗してもトークンファイルが削除されることはありません。
• アクセストークン、リフレッシュトークン、トークンエンドポイントのエラー説明がログに記録されることはありません。記録されるのはHTTPステータスとOAuthエラーコードのみです。
• ホストブリッジ呼び出しを設定した場合、MCP_HOST_BRIDGE_STATEのトークンを使用して127.0.0.1に接続します。
• チケットの件名、説明、コメント本文、ユーザー／組織／グループ／マクロ／ビュー／フィールドのテキスト、その他の外部作成文字列は、モデルに公開する前に、閉じタグをエスケープしたうえで<untrusted-content source="...">...</untrusted-content>のエンベロープで囲まれます。
• ファイルに書き込むチケットエクスポートは、システムの一時ディレクトリ内に制限され（シンボリックリンクを考慮した正規のパス包含チェックを実施）、エクスポートごとに新しく作成した専用ディレクトリ内に、所有者のみがアクセスできる権限で作成されます。指定されたファイル名のみが使用され、完全なパスはfile_pathとして返されます。既存のファイルが変更されることはありません。export_zendesk_ticketsとget_zendesk_tickets_by_idsはローカルのエクスポートファイルを書き込む可能性があるため、読み取り専用ではないと注釈されています。
• メールアドレスはネットワーク呼び出し前に形式が検証され、電話番号はE.164形式で検証されます。数値IDとページネーションパラメーターには正の整数を指定する必要があります。
• アカウントの削除、チケットの更新、チケットへのコメント追加、マクロの適用には、対応するホストがサポートデータの変更前に確認を求められるよう、マークが付けられています。

スモークテスト

MCPホストに次の実行を依頼してください。

Zendeskで未解決のチケットを一覧表示して

失敗した場合は、次の点を確認してください。

• dist/index.jsが存在すること（npm run buildを実行）
• ZENDESK_CONFIG_PATHが読み取り可能なディレクトリを指していること
• accounts.jsonに有効なサブドメイン、メールアドレス、APIトークンが含まれていること

トラブルシューティング

ライセンス

FSL-1.1-MIT — MITの将来ライセンスを含むFunctional Source License、Version 1.1です。本ソフトウェアは2030-04-08にMITライセンスへ移行します。