Zendesk MCP Server

Zendesk MCP サーバー

Zendesk 用の Model Context Protocol サーバーです。

このサーバーは、Zendesk と包括的に連携できます。次の機能を提供します。

• Zendesk のチケットとコメントを取得、管理するツール
• チケットの分析と返信文の作成に特化したプロンプト
• ナレッジベースとして Zendesk Help Center の記事にフルアクセス

セットアップ

• ビルド：uv venv && uv pip install -e .、または簡単に uv build を実行します。
• 認証を設定します：下記の認証を参照してください。
• Claude デスクトップで設定します：

{
  "mcpServers": {
      "zendesk": {
          "command": "uv",
          "args": [
              "--directory",
              "/path/to/zendesk-mcp-server",
              "run",
              "zendesk"
          ]
      }
  }
}

認証

このサーバーは OAuth で認証します。各オペレーターがそれぞれの Zendesk ログインで認証するため、API 呼び出しにはそのオペレーターの ID が付与され、Zendesk は UI とまったく同じ権限（ロール、グループの制限、チケットへのアクセス権）を適用します。投稿したコメントの作成者も本人になります。

API トークン認証も引き続き利用できますが、非推奨です。API トークンからの移行を参照してください。

1. パブリック OAuth クライアントを登録する

管理センターで Apps and integrations > APIs > OAuth clients に移動し、クライアントを作成します。

フィールド	値
クライアントの種類	パブリック — このサーバーは各オペレーターのマシン上で実行されるため、保持しておけるシークレットはありません。代わりに PKCE を使用します。
リダイレクト URL	http://localhost:4567/callback
許可するスコープ	tickets:read tickets:write ticket_attachments:read users:read hc:read

許可するスコープの設定は任意ですが、推奨されています。このクライアントからのトークンが要求できる範囲を、コードが変更された場合でも制限できます。

クライアントの識別子を控えておきます。これは下記の ZENDESK_CLIENT_ID です。

Zendesk が http://localhost:4567/callback を拒否する場合は、代わりに https://localhost を登録し、手順 3 で zendesk-auth --manual を使用してください。

2. 環境を設定する

.env.example を .env にコピーし、次の値を設定します。

ZENDESK_SUBDOMAIN=acme        # for https://acme.zendesk.com
ZENDESK_CLIENT_ID=your-client-identifier

.env をバージョン管理の対象に含めないでください。

任意の設定が 2 つあります。どちらも OAuth クライアントの設定と一致させる必要があります。

変数	デフォルト	変更する場合
ZENDESK_OAUTH_REDIRECT_URI	http://localhost:4567/callback	ポート 4567 が使用中の場合、またはクライアントに別のリダイレクト URL を登録した場合に変更します。クライアントのリダイレクト URL と完全に一致している必要があります。
ZENDESK_TOKEN_FILE	$XDG_CONFIG_HOME/zendesk-mcp/tokens.json	Docker ボリュームなど、トークンを別の場所に保存する場合に変更します。

3. このマシンを一度だけ認証する

uv run zendesk-auth

ブラウザーが開き、オペレーターにアクセスの承認を求めた後、取得したトークンがローカルに保存されます。それ以降、サーバーが自動的にアクセスを更新するため、トークンが取り消された場合や、リフレッシュトークンの有効期間（このサーバーが要求する 90 日）を過ぎるまで使用されなかった場合を除き、オペレーターが再認証する必要はありません。

リモートシェルや https://localhost を登録した OAuth クライアントなど、ブラウザーからこのマシンに接続できない場合は、代わりに貼り付け方式のフローを使用します。

uv run zendesk-auth --manual

トークンは $XDG_CONFIG_HOME/zendesk-mcp/tokens.json（デフォルトでは ~/.config/zendesk-mcp/tokens.json）に書き込まれます。ファイルは 0700 のディレクトリ内に 0600 のアクセス権で作成されます。ZENDESK_TOKEN_FILE で保存場所を変更できます。このファイルには有効な認証情報が含まれています。パスワードと同様に扱い、決してコミットしないでください。

トークン更新の仕組み

Zendesk のアクセストークンは有効期間が短く、デフォルトでは 30 分、最長でも 48 時間です。 そのため、サーバーが自動的に更新します。

• 有効期限前：保存されたトークンの有効期限が 60 秒以内に切れる場合
• 拒否されたとき：Zendesk が 401 と {"error": "invalid_token"} を返した場合。その場合、新しいトークンを使ってリクエストを 1 回再試行します。

再試行の対象となるのは invalid_token の場合だけです。スコープ不足、またはオペレーター自身の Zendesk 権限が原因で 401 や 403 が返された場合は、そのまま返されます。そのため、権限の問題が認証の不安定さのように見えることはありません。

更新のたびにリフレッシュトークンがローテーションされ、以前のトークンはすぐに無効になります。そのため、新しいペアは使用前にディスクへ書き込まれます。書き込みはアトミックに行われ、ロックファイルで保護されます。これは、複数の MCP クライアントから同時にサーバーを実行する場合に重要です。

リフレッシュトークン自体の有効期限が切れている場合、または取り消されている場合、ツールはオペレーターに zendesk-auth の再実行を促すメッセージを表示して失敗します。

スコープの選択

デフォルトのスコープで、このサーバーが公開するすべてのツールを利用できます。

スコープ	必要な対象
tickets:read	get_ticket、get_tickets、get_ticket_comments
tickets:write	create_ticket、update_ticket、create_ticket_comment
ticket_attachments:read	get_ticket_attachment
users:read	チケットの依頼者および担当者の詳細
hc:read	zendesk://knowledge-base リソース

すべてのツールが必要でない場合は、ZENDESK_OAUTH_SCOPES でスコープを絞り込めます。読み取り専用アクセスの場合は、tickets:read users:read hc:read を指定します。

スコープは許可の上限であり、権限を付与するものではありません。トークンで、認可したオペレーターに許可されている範囲を超える操作はできません。Zendesk はトークンの発行時に認識できないスコープ名も受け付けますが、その後すべてのリクエストを 403 で拒否します。そのため、zendesk-auth は比較できるように、Zendesk が実際に付与したスコープを表示します。

API トークンからの移行

Zendesk は、次のスケジュールで API トークンを廃止します。

日付	変更
2026-07-28	30 日間使用されていないトークンは自動的に無効化されます。新しいアカウントではトークンを作成できなくなります。
2026-10-27	どのアカウントでも新しい API トークンを作成できなくなります。
2027-04-30	すべての API トークンが恒久的に使用できなくなります。

それまでは ZENDESK_EMAIL と ZENDESK_API_KEY を引き続き使用でき、サーバーは初回の認証時に非推奨の警告をログに記録します。ZENDESK_CLIENT_ID を設定すると OAuth が優先されるため、古い変数を削除せずに移行できます。

期限より早く移行する理由もあります。Zendesk API トークンはアカウント単位で、スコープがありません。トークンを持つ人は、そのトークンに紐付けられたユーザーのアクセス権をすべて取得できます。多くの環境では、そのユーザーは管理者です。オペレーターごとの OAuth なら、この問題を解決できます。

クライアントクレデンシャルフローを使わない理由は何ですか？ よりシンプルで、ブラウザーの手順もリフレッシュトークンも不要ですが、そのトークンは OAuth クライアントを作成した Zendesk ユーザーに紐付けられます。すべてのオペレーターがそのユーザー、通常は管理者として操作することになり、監査ログやコメントの作成者もすべてそのユーザーになります。オペレーターに各自の Zendesk 権限だけを正確に適用することが目的であるため、要件に合うのは認可コードフローだけです。

Docker

分離されたランタイムを使用したい場合は、サーバーをコンテナー化できます。

1. .env.example を .env にコピーし、Zendesk の設定を入力します。このファイルはバージョン管理の対象外にしてください。

2. イメージをビルドします。

   docker build -t zendesk-mcp-server .
   

3. コンテナー内ではなく、ホスト上で認証します。zendesk-auth にはブラウザーとローカルのコールバックポートが必要なため、Docker の外で一度実行します。

   uv run zendesk-auth
   

4. 環境ファイルを渡し、トークン保存先をマウントしてサーバーを実行します。

   docker run --rm \
     --env-file /path/to/.env \
     --user "$(id -u):$(id -g)" \
     -e ZENDESK_TOKEN_FILE=/tokens/tokens.json \
     -v "$HOME/.config/zendesk-mcp:/tokens" \
     zendesk-mcp-server
   

   マウント先には書き込み権限が必要です。サーバーはリフレッシュトークンをローテーションするたびにファイルを書き換えるため、読み取り専用のマウントでは、トークンの有効期限が切れた際にサーバーを利用できなくなります。--user を指定すると、コンテナーは実行ユーザーと同じユーザーで動作するため、ホスト上で作成された 0600 のトークンファイルを読み取れます。

   STDIN/STDOUT 経由でコンテナーを MCP クライアントに接続する場合は、-i を追加します（Claude Code はこのモードを使用します）。デーモンとして実行する場合は、-d --name zendesk-mcp を追加します。

イメージは requirements.lock から依存関係をインストールし、非 root ユーザーに権限を降格して実行します。API トークン認証では設定がすべて環境変数から取得されるため、ボリュームは必要ありません。

Claude MCP 連携

Docker 化したサーバーを Claude Code/Desktop から使用するには、次のようなエントリーを Claude Code の settings.json に追加します。

{
  "mcpServers": {
    "zendesk": {
      "command": "/usr/local/bin/docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/zendesk-mcp-server/.env",
        "zendesk-mcp-server"
      ]
    }
  }
}

環境に合わせてパスを変更してください。ファイルを保存した後、新しい MCP サーバーが検出されるように Claude を再起動します。

開発

テストスイートを実行します。

uv pip install -e '.[test]'
pytest

テストでは HTTP をモックしており、Zendesk への接続は一切行いません。API トークンと OAuth の各経路、PKCE の導出、トークンの保存とローテーション、およびこのサーバーが Zendesk を呼び出す 4 つの方法をテストします。

リソース

• zendesk://knowledge-base：ヘルプセンターの記事全体にアクセスします。

プロンプト

analyze-ticket

Zendesk のチケットを分析し、詳細な分析結果を提示します。

draft-ticket-response

Zendesk のチケットへの返信文を作成します。

ツール

get_tickets

ページネーションに対応して、最新のチケットを取得します。

• 入力：

  • page（整数、任意）：ページ番号（デフォルトは 1）
  • per_page（整数、任意）：1 ページあたりのチケット数。最大 100（デフォルトは 25）
  • sort_by（文字列、任意）：並べ替えに使用するフィールド。created_at、updated_at、priority、status のいずれか（デフォルトは created_at）
  • sort_order（文字列、任意）：並べ替え順。asc または desc（デフォルトは desc）

• 出力：id、subject、status、priority、description、タイムスタンプ、担当者情報などの主要なフィールドに、ページネーションのメタデータを添えてチケットのリストを返します。

get_ticket

ID を指定して Zendesk のチケットを取得します。

• 入力：
  • ticket_id（整数）：取得するチケットの ID

get_ticket_comments

ID を指定して Zendesk のチケットのコメントをすべて取得します。

• 入力：
  • ticket_id（整数）：コメントを取得するチケットの ID

create_ticket_comment

既存の Zendesk チケットに新しいコメントを作成します。

• 入力：
  • ticket_id（整数）：コメントを追加するチケットの ID
  • comment（文字列）：追加するコメントのテキスト／内容
  • public（ブール値、任意）：コメントを公開するかどうか（デフォルトは true）

create_ticket

新しい Zendesk チケットを作成します。

• 入力：
  • subject（文字列）：チケットの件名
  • description（文字列）：チケットの説明
  • requester_id（整数、任意）
  • assignee_id（整数、任意）
  • priority（文字列、任意）：low、normal、high、urgent のいずれか
  • type（文字列、任意）：problem、incident、question、task のいずれか
  • tags（array[string]、任意）
  • custom_fields（array[object]、任意）

update_ticket

既存の Zendesk チケットのフィールド（ステータス、優先度、担当者など）を更新します

• 入力：
  • ticket_id（整数）：更新するチケットの ID
  • subject（文字列、任意）
  • status（文字列、任意）：new、open、pending、on-hold、solved、closed のいずれか
  • priority（文字列、任意）：low、normal、high、urgent のいずれか
  • type（文字列、任意）
  • assignee_id（整数、任意）
  • requester_id（整数、任意）
  • tags（配列[string]、任意）
  • custom_fields（配列[object]、任意）
  • due_at（文字列、任意）：ISO8601 日時