Zendesk Mcp

zendesk-mcp

Model Context Protocol サーバーです。Zendesk のチケットを読み書きするツールを、Claude Code やその他の MCP クライアントに公開します。

できること

• Zendesk のチケット、コメント、添付ファイルを検索、一覧表示（ページネーション対応）、取得
• チケットを新規作成し、既存のチケットのフィールドを更新（グループ、カスタムステータス、タグを含む）
• 公開返信と内部メモを投稿
• チケットのステータスを設定し、チケットをエージェントに割り当て
• ビューやマクロを参照して適用
• ユーザー、グループ、組織、カスタムステータスを検索
• 時間追跡のエントリを読み書き
• トラッカー（GitLab、GitHub、Jira）への引き継ぎ用に、チケットを Markdown の課題ドラフトとしてフォーマット
• チケットの分析と返信ドラフト作成用の 2 つの MCP プロンプト（analyze-ticket、draft-ticket-response）
• （任意）Zendesk ヘルプセンターの記事を MCP リソースとして公開
• Git-Zen Zendesk アプリを介して、リンクされた GitLab の課題／MR／コミットを読み取り

前提条件

• Python 3.10 以降
• Zendesk OAuth クライアント。Zendesk 管理者は次の場所で作成できます。 https://<your-subdomain>.zendesk.com/admin/apps-integrations/apis/zendesk-api/oauth_clients リダイレクト URL を http://localhost:8787/callback に設定し、スコープ read write を要求してください。

インストール

プロジェクト内の仮想環境にインストールします。venv を使用すると、zendesk-mcp とその依存関係をシステムの Python や他のプロジェクトから分離できます。以下の手順では、この方法を推奨します。

このリポジトリをクローンした状態で、次を実行します。

python3 -m venv .venv
.venv/bin/pip install --upgrade pip
.venv/bin/pip install -e .

開発用（pytest もインストールします）：

.venv/bin/pip install -e ".[dev]"

この README 全体を通して、コマンドでは .venv/bin/... を使って venv 内のバイナリを実行します。代わりに、シェルごとに一度 source .venv/bin/activate を実行してプレフィックスを省略してもかまいません。実行結果は同じです。

OAuth のセットアップ

venv の Python を使って、対話形式のセットアップを実行します。

.venv/bin/python -m zendesk_mcp setup

次の情報を求められます。

1. Zendesk のサブドメイン（例：acme.zendesk.com の場合は acme）
2. 管理者が作成した OAuth クライアント ID
3. OAuth クライアントシークレット
4. （任意）Git-Zen 連携フィールド ID。任意：Git-Zen 連携を参照してください。
5. （任意）ヘルプセンターのナレッジベースリソースを有効にするかどうか。任意：ヘルプセンターのナレッジベースを参照してください。

セットアップでは、OAuth 認証のためにブラウザーが開き、その後トークンが ~/.config/zendesk-mcp/config.json に書き込まれます（モード 0600）。

ブラウザーがない場合は、URL がターミナルに表示されます。任意のデバイスで開いて Allow をクリックし、表示されたリダイレクト URL をプロンプトに貼り付けてください。

トークンの有効期限と更新

Zendesk のアクセストークンには有効期限があります。2026-04-30 以降に作成された OAuth クライアントのデフォルトの有効期間は 30 分です。それ以前のクライアントでは、有効期限を指定しない限りトークンの有効期限はありません。セットアップでは、どちらの場合も同じ動作になるよう、24 時間のアクセストークンと 90 日間のリフレッシュトークンを要求します。サーバーはアクセストークンの期限が切れる前と、リクエスト中に Zendesk がトークンを拒否した場合に、自動的にトークンを更新します。

これを可能にするため、設定ファイルにはアクセストークンとともに refresh_token、expires_at、 client_id、client_secret も保存されます。アクセストークンと同等の信頼レベルで扱われるため、ファイルのモードは 0600 のままにしてください。OAuth クライアントからリフレッシュトークンが返されない場合は、セットアップ時にその旨が通知され、トークンはそのまま使用されます。

次の場合は .venv/bin/python -m zendesk_mcp setup を再実行してください。

• リフレッシュトークンの有効期限が切れた場合（未使用のまま 90 日が経過したとき）、または
• Zendesk で OAuth の認可を取り消した場合。

いずれの場合も、ツールは不明瞭なエラーで失敗するのではなく、Zendesk authorization failed: ... Re-run: zendesk-mcp setup を返します。

Claude Code への登録

venv の Python を絶対パスで指定して、MCP サーバーを登録します。Claude Code は有効化済みの venv を引き継がない新しいシェルでサーバーを起動するため、絶対パスが必要です。ここで python のみを指定すると、zendesk_mcp のインポートに失敗します。

ZENDESK_MCP_DIR="$(pwd)"   # run this from the repo root, after install
claude mcp add --scope user zendesk -- "$ZENDESK_MCP_DIR/.venv/bin/python" -m zendesk_mcp

または、指定したい絶対パスを直接記述します。

claude mcp add --scope user zendesk -- /absolute/path/to/zendesk-mcp/.venv/bin/python -m zendesk_mcp

次に、呼び出しごとの確認を避けるため、読み取りツールを ~/.claude/settings.json の permissions.allow に追加します。

{
  "permissions": {
    "allow": [
      "mcp__zendesk__zendesk_get_ticket",
      "mcp__zendesk__zendesk_get_tickets",
      "mcp__zendesk__zendesk_get_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context",
      "mcp__zendesk__zendesk_list_views",
      "mcp__zendesk__zendesk_get_view",
      "mcp__zendesk__zendesk_get_view_tickets",
      "mcp__zendesk__zendesk_list_macros",
      "mcp__zendesk__zendesk_preview_macro",
      "mcp__zendesk__zendesk_search_users",
      "mcp__zendesk__zendesk_get_groups",
      "mcp__zendesk__zendesk_get_group_users",
      "mcp__zendesk__zendesk_get_organization",
      "mcp__zendesk__zendesk_list_custom_statuses"
    ]
  }
}

書き込みツール（zendesk_post_comment、zendesk_post_internal_note、zendesk_set_ticket_status、zendesk_assign_ticket、zendesk_create_ticket、zendesk_update_ticket、zendesk_log_time、zendesk_add_tag、zendesk_remove_tag、zendesk_apply_macro）は、デフォルトの許可リストに意図的に含まれていません。Claude は呼び出しごとに確認を求めます。

ツールの制限

デフォルトでは、すべてのツールが有効です。たとえば、チケットのテキストを顧客が書き込み、エージェントが顧客に返信できないようにする場合など、デプロイ環境で実行可能な操作を制限するには、~/.config/zendesk-mcp/config.json またはサーバーの環境変数に次のいずれかを設定します。両方の値は組み合わせて適用されます。

設定キー	環境変数	効果
"read_only": true	ZENDESK_MCP_READ_ONLY=true	書き込みツール（コメント、メモ、ステータス、担当者の割り当て、作成／更新、タグ、マクロ、時間の記録）を登録しません
"disabled_tools": ["zendesk_post_comment"]	ZENDESK_MCP_DISABLED_TOOLS=zendesk_post_comment,zendesk_apply_macro	指定したツールを登録しません

無効化されたツールは登録されないため、モデルから確認したり呼び出したりできません。どのツールにも一致しない名前は stderr に出力されます。

ツール

チケット

チケットレコードを返すツールには、チケットが届いたチャネル（Zendesk の via.channel：web、email、api など）を示す channel が含まれます。Zendesk からチャネルが提供されない場合は null になります。zendesk_get_ticket は、{id, value} のペアのリストとして custom_fields も返します。チケットに設定されていないフィールドの値は null です。

ツール	機能
zendesk_search_tickets	ステータス、優先度、種類、担当者、リクエスター、タグ、キーワードでチケットを検索します。各結果には channel が含まれます
zendesk_get_tickets	ページネーションと並べ替え（page、per_page、sort_by、sort_order）を指定してチケットを一覧表示します。各チケットには channel が含まれます
zendesk_get_ticket	channel と custom_fields を含む、1 件のチケットのメタデータを取得します
zendesk_create_ticket	新しいチケットを作成します（subject、description、任意の priority/type/assignee_id/requester_id/tags/custom_fields）
zendesk_update_ticket	既存のチケットのフィールドを 1 つ以上更新します（status、priority、subject、type、assignee_id、requester_id、group_id、custom_status_id、tags、custom_fields、due_at）
zendesk_get_comments	チケットの会話スレッドを取得します
zendesk_list_attachments	チケットの添付ファイルを一覧表示します
zendesk_download_attachment	添付ファイルをローカルのキャッシュディレクトリにダウンロードします。URL は使用中の Zendesk ホスト上のものである必要があります。また、dest_dir はキャッシュ内、または設定の attachment_allowed_dest_dirs に記載されたディレクトリ内である必要があります
zendesk_ticket_to_gitlab_context	チケットとその会話を、Markdown のイシュードラフトとして整形します
zendesk_post_comment	チケットに公開返信を投稿します
zendesk_post_internal_note	チケットにエージェント専用の内部メモを投稿します
zendesk_set_ticket_status	チケットのステータスを設定します（new、open、pending、hold、solved、closed）
zendesk_assign_ticket	メールアドレスまたは me を指定して、チケットをエージェントに割り当てます

タグ

ツール	機能
zendesk_add_tag	チケットにタグを追加します（冪等）
zendesk_remove_tag	チケットからタグを削除します（冪等）

ビューとマクロ

ツール	説明
zendesk_list_views	有効なビューをすべて一覧表示します
zendesk_get_view	ビューのフィルター条件と実行設定を取得します
zendesk_get_view_tickets	現在ビューに一致するチケットを取得します。各チケットには channel が含まれます
zendesk_list_macros	有効なマクロとそのアクションを一覧表示します
zendesk_preview_macro	マクロによって行われる変更をプレビューします
zendesk_apply_macro	チケットにマクロを適用します（フィールドの変更とコメントの投稿を適用します）

ユーザー、グループ、組織

ツール	説明
zendesk_search_users	名前またはメールアドレスでユーザーを検索します
zendesk_get_groups	有効なグループをすべて一覧表示します
zendesk_get_group_users	グループのメンバーを一覧表示します
zendesk_get_organization	カスタムフィールドを含む組織情報を取得します
zendesk_list_custom_statuses	カスタムチケットステータスとその ID をすべて一覧表示します

時間追跡

ツール	説明
zendesk_get_time_tracking	チケットの時間追跡エントリを読み取ります
zendesk_log_time	チケットに時間エントリを記録します

Git-Zen 連携

ツール	説明
zendesk_get_git_zen_links	（Git-Zen のみ）チケットにリンクされた GitLab の課題／MR／コミットを取得します

プロンプト

サーバーは 2 つの MCP プロンプトを公開しており、一部のクライアント（例：Claude Desktop）ではスラッシュコマンドとして表示されます。

プロンプト	引数	説明
analyze-ticket	ticket_id	モデルにチケットを取得させ、概要、ステータス／時系列、主なやり取りの要点を作成させます
draft-ticket-response	ticket_id	モデルにチケットを取得させ、顧客向けの返信案を作成させます（投稿前に確認ステップがあります）

オプション：Git-Zen 連携

Zendesk インスタンスで Git-Zen アプリを使用している場合、zendesk_get_git_zen_links ツールでそのカスタムフィールドのペイロードを読み取れます。Admin → Tickets → Fields でインスタンスの Git-Zen カスタムフィールド ID（数値）を確認し、.venv/bin/python -m zendesk_mcp setup の実行時に設定するか、~/.config/zendesk-mcp/config.json を編集して次を追加します。

{
  "git_zen_field_id": 12345678901234
}

これを設定しない場合、zendesk_get_git_zen_links は「not configured」というメッセージを返します。

オプション：ヘルプセンターのナレッジベース

Zendesk インスタンスに公開済みのヘルプセンターがある場合、そのセクションと記事を zendesk://knowledge-base MCP リソースとして公開できます。このリソースは、すべてのセクションと記事を含む 1 つの JSON ドキュメントを返し、1 時間キャッシュします。

これはオプトイン方式です。有効にするには、.venv/bin/python -m zendesk_mcp setup の実行中に表示されるプロンプトに「y」と回答するか、~/.config/zendesk-mcp/config.json に次を追加します。

{
  "knowledge_base_enabled": true
}

フラグがない場合、または false の場合、ヘルプセンターがないインスタンスでサーバーのリソース一覧が空のままになるよう、このリソースは登録されません。

オプション：キャッシュ外への添付ファイルのダウンロード

zendesk_download_attachment は、デフォルトで ~/.cache/zendesk-mcp/attachments/<ticket_id>/ にファイルを書き込みます（attachment_cache_dir で設定できます）。dest_dir 引数を指定すると別の場所にダウンロードできますが、添付ファイルの内容はチケットの作成者が管理するため、このツールで指定できる dest_dir はキャッシュ内、または明示的に許可したディレクトリ内に限られます。許可するディレクトリを ~/.config/zendesk-mcp/config.json に追加します。

{
  "attachment_allowed_dest_dirs": ["/home/me/work/support_bundles"]
}

チェックの前にパスが解決されるため、.. セグメントやシンボリックリンクを使って許可されたディレクトリの外に出ることはできません。許可された範囲外の dest_dir は、ダウンロード開始前に拒否されます。

ダウンロード URL は、設定済みのサブドメインに対する <subdomain>.zendesk.com 上の https URL でなければなりません。これ以外の URL はツールによって拒否されるため、OAuth トークンが別のホストに送信されることはありません。アーカイブはエントリ数 10,000 件、展開後のサイズ 256 MiB に制限されます。また、通常のファイルまたはディレクトリではない tar メンバーはスキップされます。

開発

python3 -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

CI では Python 3.10、3.11、3.12 でテストが実行されます（.github/workflows/test.yml を参照）。

リリース

pyproject.toml、mcpb/pyproject.toml（バージョンと zendesk-mcp== のピン留めの両方）、mcpb/manifest.json、server.json（両方のフィールド）のバージョンを更新し、v* タグをプッシュします。これにより .github/workflows/release.yml が実行され、PyPI への公開、MCPB バンドルのパッケージ化、MCP Registry への server.json の公開、GitHub リリースの作成が行われます。

タグ付けの前に各バージョンが一致していることを確認してください。一致しない場合、リリースはすぐに失敗します。

python3 .github/scripts/check_versions.py 0.1.5

ライセンス

Apache-2.0