zendesk-mcp-server

Zendesk MCP サーバー

Model Context Protocol（MCP）サーバーです。ZendeskをAIアシスタントに組み込み、会話の両側をサポートします。

エージェント向け：ヘルプセンターから回答を見つけ、記事の下書き、更新、翻訳を行いながら言語間の同期を保ちます。また、コメント、トリアージ、画像添付を含め、サポートチケットを最初から最後まで処理します。

お客様向け：ヘルプセンターの「リクエストを送信」フォームと同じ入口を提供します。リクエストの種類を選ぶと、フォームで実際に尋ねられる質問に沿って案内されます。スクリーンショットを添付した後は、チケットの返信を読んだり、返信を送ったり、解決後にチケットを閉じたりできます。エンドユーザーモードをご覧ください。

すべてを、アプリを切り替えることなく、自然な言葉で行えます。

Microsoft 365 Copilot 向け Zendesk エージェントとおおむね同じ機能を提供しますが、特定のベンダーに縛られません。Claude Desktop、Claude Code、Cursor、VS Codeなど、あらゆるMCPクライアントで使えます。また、共有の管理者キーではなく、常に各ユーザー自身のZendesk権限で動作します。

アシスタントでできること

自然な言葉で尋ねると、アシスタントが文脈と意図を判断し、適切なツールを呼び出します。

• ヘルプセンターで回答を見つけます。「ソフトウェアライセンスを申請するには？」や「休暇の方針は？」と尋ねると、キーワードではなく意味に基づいて適切な記事を見つけます。
• 会話から離れずにチケットを作成、表示、更新できます。チケットを作成し、ステータスを確認し、公開返信や内部メモを追加し、優先度や担当者を変更して、解決済みにできます。
• レポート作成や迅速な判断のために、チケットを要約します。アシスタントが詳細とコメントのスレッド全体を取得し、要点を一文でまとめます。
• チケットに添付されたスクリーンショットや写真を読み取ります。エラーダイアログ、UIのキャプチャ、製品の写真を画像としてアシスタント自身のモデルに渡すため、内容を説明したり、画像に示された情報に基づいて対応したりできます。
• 自然な言葉でキューを検索し、トリアージできます。「今週の請求関連の未解決チケットを見せて」と尋ねられます。
• ナレッジベースの記事を下書きし、管理できます。新しい記事を作成したり、大きな記事を一度に1つのセクションずつ改訂したりできるため、HTML本文全体をモデルとの間でやり取りする必要はありません。
• エージェントではなくお客様としてリクエストを送信し、その後も進捗を確認できます。ベンダーが提供するリクエストの種類から選び、フォームに表示される質問だけに回答して、返信内容、自分の返信内容、完了したかどうかを確認できます。

このサーバーを選ぶ理由

Zendesk の多くの統合では、共有の管理者 API キーが使われます。これにより、すべてのユーザーにすべてのチケットへのフルアクセス権が与えられ、固定されたツール一式が付け加えられます。このサーバーは異なる設計です。

• ユーザーごとの認証は OAuth のみです。どちらのトランスポートでも OAuth 2.1 PKCE を使用します。各ユーザーが自分の Zendesk 認証情報でサインインするため、アシスタントはそのユーザーに許可された範囲だけを閲覧・操作できます。Zendesk に直接サインインした場合と同じアクセス範囲です。静的 API トークンには意図的に対応していません（対応していない理由）。
• 1 つのサーバーで 2 つの対象ユーザーに対応します。認証は共有の管理者キーではなくユーザーごとに行われるため、同じインストールをエージェントにも顧客にも提供できます。エンドユーザー向けの機能は、リクエスター用に Zendesk が予約している API パスを使用する名前空間として有効にします。多くの Zendesk MCP サーバーは、設計上エージェント専用です。
• セクション単位の記事編集に対応します。大規模なヘルプセンターの記事では、アシスタントに HTML 本文全体を渡すのではなく、h1／h2／h3 見出しで解析したセクションを 1 つずつ読み取り、書き換えられます。対象を絞った編集では、トークン数を 10 分の 1 から 100 分の 1 に削減できます。
• マルチモーダルな添付ファイルに標準対応します。チケットの画像は MCP のネイティブな画像コンテンツとして返されるため、クライアント独自のモデル（Claude、GPT、Gemini など）が画像を直接認識できます。サーバー側の画像認識モデルも、追加の API キーも不要で、特定のプロバイダーに縛られることもありません。画像以外の添付ファイルはテキスト参照として返され、画像の上限はどちらも設定可能です。
• 公開するツールの範囲を制限できます。すべての操作を個別のツールとして公開することも、名前空間プロキシにまとめることも、すべてを単一の統合ツールに集約することもできます。また、名前空間単位、または読み取り専用の操作に絞ってフィルタリングできるため、各コンテキストには必要な範囲だけを読み込めます（ツールの範囲を参照）。
• 2 種類のデプロイ方法で、認証の仕組みは共通です。stdio MCP サーバーとして開発用マシンで実行することも、HTTP 経由で接続するプライベートなリモート MCP サーバーとしてデプロイすることもできます。後者では、リクエストごとに Zendesk セッションを 1 つ使用し、各クライアントが自身のユーザーのトークンを送信します。
• 軽量なスタックです。公式 MCP TypeScript SDK（@modelcontextprotocol/server）と zod を使用し、Zendesk Support API とヘルプセンター（Guide）API に接続します。

次の場合は、別のソリューションをお探しください。

• Support と Guide 以外の Zendesk 製品（Talk、Explore の分析機能、Sell）が必要な場合。これらのエンドポイントには対応していません。
• 単一の共有サービスアカウント、または静的 API トークン認証が必要な場合。このサーバーは、意図的にどちらにも対応していません（以下を参照）。

このサーバーが 対応していないこと

API トークン認証には対応していません。このサーバーが使用するのは OAuth 2.1 PKCE のみです。どのトランスポートでも、ZENDESK_EMAIL + ZENDESK_API_TOKEN（Basic 認証）モードはありません。これは、次の 2 つの理由による意図的な仕様です。

1. API トークンのセキュリティは不十分です。 Zendesk API トークンは有効期間が長い静的な共有シークレットで、発行者であるユーザーのすべての権限を引き継ぎます。ユーザーごとのアクセス範囲の制限、短い有効期限、ユーザーごとの同意や取り消しはありません。OAuth 2.1 PKCE では、代わりにユーザーごとに取り消し可能なトークンが発行されます。
2. API トークンでは規模を拡大できません。 1 つの静的な認証情報では、操作を個々のユーザーに紐付けられず、きめ細かく取り消すこともできません。また、複数ユーザー向けのリモートデプロイも安全ではありません。HTTP 経由では、発行者であるユーザーの権限がすべての呼び出し元に公開されるためです。

API トークンやサービスアカウント方式（共有アカウントを使うヘッドレス CI など）が必要な場合は、それに対応している他の Zendesk MCP サーバーをご利用ください。いくつかのサーバーを参考プロジェクトと関連プロジェクトに掲載しています。

クイックスタート：ローカル（stdio）

標準的な構成は、開発者 1 人、Zendesk アカウント 1 つ、ブラウザーでの OAuth 2.1 PKCE です。Node.js >= 22 と Zendesk のインスタンス（Support または Suite）が必要です。

インストール

# Run without installing
npx -y @fruggr/zendesk-mcp-server <your-subdomain>

# Or install globally
npm install -g @fruggr/zendesk-mcp-server
zendesk-mcp-server <your-subdomain>

サインインには Zendesk OAuth クライアントが必要なので、まず登録してください（次のセクションを参照）。

Zendesk OAuth の設定

1. Admin Center → Apps and integrations → APIs → OAuth Clients に移動します
2. public クライアントを作成します：
   • Identifier：<your-subdomain>_zendesk（または ZENDESK_OAUTH_CLIENT_ID を設定します）
   • Redirect URL：http://localhost:27439/callback（ポートを変更する場合は、 OAUTH_CALLBACK_PORT / --callback-port に合わせて変更します。Zendesk では、1 行につき 1 つ、複数のリダイレクト URL を設定できます）

クライアントで許可するスコープが制限されている場合は、read が必要です。また、 サーバーを --read-only 付きで実行しない場合は write も必要です。--read-only を指定すると、Zendesk には read スコープのみを要求します。

最初のツール呼び出し時に、サーバーはサインインフローを開始します。ブラウザーウィンドウを 開き、ツールメッセージで認証 URL を返します。サインインが完了するまで呼び出しは待機しない ため、ブラウザーで認証してからリクエストを再試行してください。トークンは所有者のみが アクセスできるファイルに保存され、再起動後も再利用されるため、MCP クライアントがサーバーを 再起動するたびに認証する必要はありません（パスと上書き設定： OAUTH_TOKEN_FILE）。複数のインスタンスを 同時に実行できます。たとえば、読み書き可能なインスタンスと --read-only インスタンスを、 認証情報を共有せずに併用できます。

MCP クライアントの設定

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
    }
  }
}

claude mcp add zendesk -- npx -y @fruggr/zendesk-mcp-server <your-subdomain> --mode single

{
  "servers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "@fruggr/zendesk-mcp-server", "<your-subdomain>", "--mode", "single"]
    }
  }
}

問題が解決しない場合は、トラブルシューティングを参照してください。

クイックスタート：リモート（HTTP）

実験的機能です。 HTTP トランスポートは提供されていますが、すべての MCP クライアントで、 実際の Zendesk テナントを使ったエンドツーエンドのテストはまだ実施されていません。 サポート対象の方法はローカル stdio です。

Zendesk アカウント1 つ専用の、プライベートなリモート MCP サーバーをデプロイすることもできます。 これは独自の OAuth 認可サーバーとして動作します。claude.ai や ChatGPT などのウェブクライアントは URL を指定して追加し、自身を登録します。各ユーザーはこのサーバーを介して Zendesk にサインインするため、 共有管理者キーやクライアントごとの Zendesk 設定は不要です。各リリースには、署名とアテステーションが 付与された、セキュリティ強化済みの distroless コンテナーイメージ （ghcr.io/fruggr/zendesk-mcp-server）も含まれています。完全なガイドでは、イメージ、Zendesk OAuth クライアントに追加する 1 つのリダイレクト URL、マスターシークレットとグラントストア、リバースプロキシ 背後での --public-url、信頼済みクライアント、MCP クライアントの設定、CORS、および運用者が担う作業を 説明しています： docs/http-deployment.md。

ツールの構成

ツールは名前空間ごとに分類されています。チケット、ヘルプセンター、ユーザーと組織、検索、コネクターの設定 — SLA アラートのしきい値など、Zendesk には一切書き込まれない、このサーバー独自のユーザーごとの設定 — と、リクエスト — エンドユーザー向けの機能で、オプトイン方式です。エンドユーザーモードで説明しています。このサーバーは、粒度とコンテキスト予算のバランスを選べるように、3 つのモードのいずれかでツールを登録します。

• all：各操作を個別のツールとして登録します。ツール選択の精度が高いクライアント向けです。
• namespace（デフォルト）：名前空間ごとにプロキシツールを 1 つ登録します。両者のバランスが取れた方式です。
• single：単一の zendesk ツールを登録します。利用可能なツール枠が少ないモデル向けです（コネクター独自の設定には、別途 connector_preferences プロキシが用意されます）。

プロキシには { "operation": "<tool_name>", "params": { … } } を渡します。params は元のスキーマに照らして検証されます。--namespace、--tool、--read-only は、プロキシの作成前にツールを絞り込むため、各プロキシには絞り込み後に残った操作だけが記載されます。

インベントリを選ぶ方法は 1 つ（--namespace／--tool）で、それを --mode でパッケージ化し、--read-only でさらに絞り込みます。組み合わせが明確でない場合は、推測せずに --print-tools を使ってください。認証情報がなくても、サーバーが公開する内容を確認できます。

各ツールとその説明、および read／write モードについては、**docs/mcp-tools-reference.mdを参照してください。フラグと使用例については、docs/configuration.md**を参照してください。

エンドユーザーモード

上記の機能はすべて、Zendesk のエージェント向けです。このセクションでは、もう一方の利用者、つまり顧客について説明します。

ウェブでは、顧客はヘルプセンターの「リクエストを送信」フォームからチケットを作成します。リクエストの種類を選び、その種類に応じた項目に入力し、ファイルを添付して、後から返信を確認しに戻ります。エンドユーザーモードでは、同じ一連の操作をアシスタント内で行えます。

対象ユーザー

顧客がすでに利用している場所でサポートを提供するために、顧客を MCP サーバーへ案内するベンダー向けです。顧客は自分でサーバーをインストールし、自分のヘルプセンターアカウントでサインインします。他の人の情報が表示されることはありません。

有効にする方法

エンドユーザー向けツールは requests 名前空間にあり、オプトイン方式です。エージェント向けのインストールに、他の利用者向けのツールが含まれるべきではありません。また、そのうちの 1 つであるリクエストの解決済みへの変更は、エージェントトークンでは機能しません。Zendesk はリクエストを受け付けますが、何もせずに処理を終えます。顧客がナレッジベースを検索できれば、そもそもチケットを作成する必要がないことも多いため、help_center もあわせて提供すると便利です。

フラグと、組み合わせによって公開される内容をサーバーに出力させる方法については、**docs/configuration.md**を参照してください。

対応する操作

• 利用可能なリクエストの種類を確認する。 ベンダーが提供するフォームを、顧客向けの名称で表示します。
• 各フォームで何が求められるかを確認する。 フォーム上の質問、必須項目、およびドロップダウンの正確な選択肢を確認できます。これにより、アシスタントはペイロードを推測せず、会話を通じて情報を集められます。
• リクエストを送信する。 添付ファイルにも対応しています。
• リクエストを追跡する。 リクエストの一覧表示、会話全体を含む個別リクエストの閲覧（各返信の投稿者を示し、サポートエージェントにはその旨を表示）、返信、および必要に応じた解決済みへの変更ができます。

Zendesk アカウントに必要なもの

エージェント側で必要なものに加えて、必要なのは 1 つだけです。少なくとも 1 つのチケットフォームがエンドユーザー向けに公開されている必要があります。顧客がそこからフォームを選ぶためです。サインインは、設計上、ブラウザーを介した対話形式で行います。エンドユーザートークンを取得するスクリプト実行やヘッドレスの方法はありません。これは、第三者が顧客になりすましてサインインすることを防ぐための仕組みでもあります。

前提条件の詳細については、**docs/configuration.mdを参照してください。ターミナルを使わない方向けの手順を追ったガイドについては、docs/end-user-onboarding.md**を参照してください。

顧客にできないこと — そして、できるべきではないこと

顧客にできることは、エージェントより少ないです。それは不足ではなく、そうあるべき姿です。

• 自分のチケットのみ。 当サーバーではなく、Zendesk によって強制されます。
• 内部メモは、どちらの方向でも不可。 エージェント専用のメモは、このインターフェースが返す内容には一切表示されません。Zendesk がリクエスター向けのチケット表示から完全に除外します。
• 優先度とタイプの設定は不可。 顧客が設定しても、Zendesk がどちらも破棄します。トリアージはエージェントが引き続き担当します。
• エージェントが対応を開始した後に限り、チケットをクローズできます。 それまでは Zendesk がリクエスターによる解決を許可しないため、このツールはその旨を伝え、できるふりはしません。
• チケット全体を対象とする検索、ユーザー検索、ビュー、マクロは利用できません。

ヘルプセンターのコンテキスト

ツールに加えて、このサーバーは あなたの ヘルプセンターの構造を LLM に渡します。有効なロケール、ID 付きのカテゴリ → セクションのツリー、公開範囲のセグメント、権限グループが含まれます。これらを使うことで、名前を推測したり曖昧一致させたりせず、実際の ID を使用できます。すべて MCP ネイティブのチャネルを通じて渡されます。具体的には、initialize で送信される instructions の内容と、トポロジーおよび個々の記事の読み取り（または固定）に使う、プル専用のリソースです。リソースは呼び出し元自身のトークンを使って取得されます。リソースをサポートしていないクライアントは、これらを暗黙的に無視します。

公開される内容、注目記事の事前リスト取得に必要なリクエスト数、各項目を無効にする方法については、docs/help-center-context.md をご覧ください。

設定

CLI フラグ（--mode、--namespace、--read-only、--transport、--public-url など）と環境変数（ZENDESK_SUBDOMAIN、OAUTH_TOKEN_FILE、PUBLIC_URL、添付ファイルのビジョン機能の上限）の完全なリファレンスは、docs/configuration.md にあります。各変数には個別のアンカーがあるため、特定の設定に直接リンクできます。

トラブルシューティング

OAuth ログイン時にブラウザーが開かない、コールバックのポートがすでに使用されている、毎回再認証が必要になる、Guide 管理用エンドポイントで Permission denied が表示されるといった問題については、docs/troubleshooting.md で説明しています。OAuth フローの全トレースを確認するには、LOG_LEVEL=debug を設定して再起動してください。

開発

リポジトリとツールチェーンのセットアップ、開発モード、PR ブランチのテスト方法については、CONTRIBUTING.md をご覧ください。アーキテクチャとコードスタイルの規約は、AGENTS.md に記載されています。

FAQ

どの Zendesk 製品に対応していますか？ Zendesk Support（チケット、ユーザー、組織）と Help Center / Guide（記事、セクション、カテゴリ、翻訳、ラベル、コンテンツタグ、セグメント、添付ファイル）に対応しています。Talk、Explore、Sell は対象外です。

Zendesk の管理者 API キーは必要ですか？ いいえ。また、このサーバーは管理者 API キーをサポートしていません。各ユーザーが自分の認証情報で認証し、サーバーはそのユーザーに許可された権限だけで動作します（理由）。

npx 経由で安全に実行できますか？ リリースは npm Trusted Publishing（OIDC）を介して CI から公開されるため、各バージョンにはビルドの来歴を示す証明が付与されています。npm ページで検証できます。サーバーがシークレットをログに出力することはありません。

コントリビューション

人間の作成者がすべての行を読み、検証している限り、AI の支援を受けたものも含め、プルリクエストを歓迎します。ガイド、作成者用チェックリスト、レビューのワークフローについては、CONTRIBUTING.md をご覧ください。

バージョンには SemVer を採用し、Conventional Commits に基づいて自動リリースしています。履歴は CHANGELOG.md にあります。

着想元と関連プロジェクト

このプロジェクトは、以下を参考にして開発されました。

• 公式の Zendesk API ドキュメント
• mattcoatsworth/zendesk-mcp-server
• koundinya/zd-mcp-server

ライセンス

MIT

Fruggr プロジェクトのために、Digital4better が開発・保守しています。