Skip to main content
Glama

zendesk-mcp

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

機能

  • Zendesk のチケット、コメント、添付ファイルを検索・一覧表示(ページング対応)・取得

  • 新規チケットの作成、既存チケットのフィールド更新(グループ、カスタムステータス、タグを含む)

  • 公開返信と内部メモの投稿

  • チケットステータスの設定とエージェントへの割り当て

  • ビューとマクロの閲覧・適用

  • ユーザー、グループ、組織、カスタムステータスの検索

  • 時間追跡エントリの読み書き

  • チケットを Markdown の issue ドラフトに整形し、トラッカー(GitLab、GitHub、Jira)へ引き継ぎ

  • チケット分析と返信ドラフト作成のための 2 つの MCP プロンプト(analyze-ticket、draft-ticket-response)

  • (オプション)Zendesk Help Center の記事を MCP リソースとして公開

  • (オプション)Git-Zen Zendesk アプリ経由でリンクされた GitLab の issue / MR / commit を読み取り

Related MCP server: Zendesk MCP Server

前提条件

  • 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 をリクエストしてください。

インストール

プロジェクトローカルの virtualenv にインストールします。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/... のバイナリを使用しています。代わりに source .venv/bin/activate をシェルごとに実行してプレフィックスを省略しても構いません — 結果は同じです。

OAuth セットアップ

venv の Python を使用して対話型セットアップを実行します:

.venv/bin/python -m zendesk_mcp setup

以下の入力を求められます:

  1. Zendesk サブドメイン(例: acme(acme.zendesk.com の場合))

  2. 管理者が作成した OAuth クライアント ID

  3. OAuth クライアントシークレット

  4. (オプション)Git-Zen 統合フィールド ID — オプション: Git-Zen 統合 を参照

  5. (オプション)Help Center ナレッジベースリソースを有効にするかどうか — オプション: Help Center ナレッジベース を参照

セットアップは OAuth 認証ステップのためにブラウザを開き、その後トークンを ~/.config/zendesk-mcp/config.json(モード 0600)に書き込みます。

ブラウザがない場合、URL がターミナルに表示されます — 任意のデバイスで開き、許可 をクリックして、表示されたリダイレクト 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 が呼び出しごとに確認を求めます。

ツール

チケット

ツール

機能

zendesk_search_tickets

ステータス、優先度、タイプ、担当者、リクエスター、タグ、キーワードでチケットを検索

zendesk_get_tickets

ページングと並べ替えに対応したチケット一覧(page、per_page、sort_by、sort_order)

zendesk_get_ticket

1 件のチケットのメタデータを取得

zendesk_create_ticket

新規チケットを作成(件名、説明、オプションで優先度/タイプ/担当者 ID/リクエスター ID/タグ/カスタムフィールド)

zendesk_update_ticket

既存チケットの 1 つ以上のフィールドを更新(ステータス、優先度、件名、タイプ、担当者 ID、リクエスター ID、グループ ID、カスタムステータス ID、タグ、カスタムフィールド、期日)

zendesk_get_comments

チケットの会話スレッドを取得

zendesk_list_attachments

チケットの添付ファイル一覧を取得

zendesk_download_attachment

添付ファイルをローカルのキャッシュディレクトリにダウンロード

zendesk_ticket_to_gitlab_context

チケットとその会話を Markdown の issue ドラフトに整形

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

ビューに現在一致するチケットを取得

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 の issue / MR / commit を取得

プロンプト

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

プロンプト

引数

機能

analyze-ticket

ticket_id

モデルにチケットを取得させ、要約、ステータス/タイムライン、主要なやり取りのポイントを生成させる

draft-ticket-response

ticket_id

モデルにチケットを取得させ、顧客向けの返信ドラフトを作成させる(投稿前に確認ステップあり)

オプション: Git-Zen 統合

Zendesk インスタンスで Git-Zen アプリを使用している場合、zendesk_get_git_zen_links ツールはそのカスタムフィールドのペイロードを読み取れます。インスタンスの Git-Zen カスタムフィールド ID を 管理 → チケット → フィールド で見つけてください(数値 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」メッセージを返します。

オプション: Help Center ナレッジベース

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

これはオプトインです。.venv/bin/python -m zendesk_mcp setup の際にプロンプトで「y」と答えるか、~/.config/zendesk-mcp/config.json に以下を追加することで有効にできます:

{
  "knowledge_base_enabled": true
}

フラグが指定されていない場合や false の場合は、リソースは登録されず、Help Center を持たないインスタンスではサーバーのリソースリストが空のままになります。

開発

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 レジストリへの server.json の公開、GitHub リリースの作成が行われます。

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

python3 .github/scripts/check_versions.py 0.1.5

ライセンス

Apache-2.0

Available Tools

29 tools
zendesk_add_tagA

Add a tag to a Zendesk ticket. Idempotent: adding an existing tag returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.

Inputs: tag (required), ticket_id (required). Returns: result

zendesk_apply_macroA

Apply a macro to a Zendesk ticket. Fetches the macro preview, applies field changes, and posts any comment included in the macro. Returns JSON with id, status, tags, applied_changes, comment_added.

Inputs: macro_id (required), ticket_id (required). Returns: result

zendesk_assign_ticketA

Assign a Zendesk ticket to an agent by their email address. Pass 'me' as assignee_email to assign the ticket to yourself (the authenticated user).

Inputs: ticket_id (required), assignee_email (required). Returns: result

zendesk_create_ticketA

Create a new Zendesk ticket. subject and description are required. priority: low/normal/high/urgent. type: problem/incident/question/task. requester_id/assignee_id are user IDs (integers). custom_fields is a list of {id, value} dicts. Returns JSON of the created ticket.

Inputs: subject (required), description (required), tags, type, +4 more. Returns: result

zendesk_download_attachmentA

Download a Zendesk attachment. Obtain attachment_url and filename from zendesk_list_attachments. ticket_id is required for cache organization. Optional dest_dir overrides the default cache location; the file is written there and (for archives) extracted alongside it. Archives return a file list and unpack_dir — read individual files with your normal file tools. PDFs return up to ~500KB of extracted text. Images are base64-encoded.

Inputs: filename (required), ticket_id (required), attachment_url (required), dest_dir. Returns: result

zendesk_get_commentsA

Get all comments (public replies and internal notes) for a Zendesk ticket. Includes attachment metadata but does not download files.

Inputs: ticket_id (required). Returns: result

zendesk_get_groupsA

List all active Zendesk groups (excluding deleted). Returns JSON array of {id, name}.

Inputs: no named parameters. Returns: result

zendesk_get_group_usersB

List the members of a Zendesk group. Returns JSON array of {id, name, email}.

Inputs: group_id (required). Returns: result

zendesk_get_organizationB

Fetch a Zendesk organization including its custom fields and tags. Returns JSON with id, name, organization_fields, tags, created_at, updated_at.

Inputs: organization_id (required). Returns: result

zendesk_get_ticketA

Get a Zendesk ticket by ID. Returns ticket fields including status, priority, requester, assignee, tags, and description.

Inputs: ticket_id (required). Returns: result

zendesk_get_ticketsA

List Zendesk tickets with pagination. page: 1-based page number. per_page: max 100. sort_by: created_at, updated_at, priority, or status. sort_order: asc or desc. Returns tickets plus pagination metadata.

Inputs: page, sort_by, per_page, sort_order. Returns: result

zendesk_get_time_trackingA

Get time tracking data for a Zendesk ticket. Returns total time spent and time spent on the last update, in both seconds and human-readable format (e.g. '2h 15m').

Inputs: ticket_id (required). Returns: result

zendesk_get_viewA

Get a Zendesk view's definition including filter conditions and execution settings. Returns JSON with id, title, active, conditions, execution.

Inputs: view_id (required). Returns: result

zendesk_get_view_ticketsB

Get the tickets currently matching a Zendesk view. Returns JSON array of tickets with essential fields.

Inputs: view_id (required). Returns: result

zendesk_list_attachmentsA

List all attachments across all comments for a Zendesk ticket. Returns filename, content type, size, and download URL for each. Use zendesk_download_attachment to fetch file contents.

Inputs: ticket_id (required). Returns: result

zendesk_list_custom_statusesA

List all custom ticket statuses defined in Zendesk. Returns JSON array of {id, agent_label, end_user_label, status_category, active, default}. Use the id when setting custom_status_id on a ticket.

Inputs: no named parameters. Returns: result

zendesk_list_macrosA

List all active Zendesk macros with their actions. Returns JSON array of {id, title, description, actions: [{field, value}]}.

Inputs: no named parameters. Returns: result

zendesk_list_viewsA

List all active Zendesk views. Returns JSON array of {id, title}.

Inputs: no named parameters. Returns: result

zendesk_log_timeA

Log time spent on a Zendesk ticket. Adds seconds to the running total and records it as the last-update time. Returns logged amount and new total in seconds and human-readable format.

Inputs: seconds (required), ticket_id (required). Returns: result

zendesk_post_commentA

Post a public reply on a Zendesk ticket. The reply is visible to the requester. Use for customer-facing responses.

Inputs: body (required), ticket_id (required). Returns: result

zendesk_post_internal_noteA

Post an internal note on a Zendesk ticket. Internal notes are only visible to agents and are not sent to the requester.

Inputs: body (required), ticket_id (required). Returns: result

zendesk_preview_macroA

Preview the effect a macro would have (without applying it). Returns the result payload from Zendesk's apply preview endpoint.

Inputs: macro_id (required). Returns: result

zendesk_remove_tagA

Remove a tag from a Zendesk ticket. Idempotent: removing a tag that isn't present returns the current tag list without modifying the ticket. Returns JSON with ticket_id and current tags.

Inputs: tag (required), ticket_id (required). Returns: result

zendesk_search_ticketsA

Search Zendesk tickets by keyword and/or status. keywords: free-text search (e.g. 'login failure LDAP'). status: new, open, pending, hold, solved, closed — leave empty for all statuses. Returns id, subject, status, requester, assignee, and dates.

Inputs: limit, status, keywords. Returns: result

zendesk_search_usersA

Search Zendesk users by name or email. Returns JSON array of {id, name, email, role}.

Inputs: query (required). Returns: result

zendesk_set_ticket_statusB

Set the status of a Zendesk ticket. Valid statuses: new, open, pending, hold, solved, closed.

Inputs: status (required), ticket_id (required). Returns: result

zendesk_ticket_to_gitlab_contextA

Format a Zendesk ticket and its comments as an issue draft. Returns Markdown with ticket metadata, full conversation, and an empty Steps to Reproduce section. Use this output as the description when creating an issue in your tracker.

Inputs: ticket_id (required). Returns: result

zendesk_update_ticketA

Update one or more fields on a Zendesk ticket. Pass only the fields you want to change. status: new/open/pending/hold/solved/closed. priority: low/normal/high/urgent. type: problem/incident/question/task. assignee_id, requester_id, group_id, custom_status_id are integer IDs. due_at is ISO8601. Returns JSON of the refreshed ticket.

Inputs: ticket_id (required), tags, type, due_at, +8 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 29 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose, even where operations appear similar (e.g., get_ticket, get_tickets, search_tickets). Descriptions clarify when to use each, and there is no meaningful overlap that would cause an agent to select the wrong tool.

    Naming Consistency4/5

    All tools share the 'zendesk_' prefix and mostly follow a verb_noun pattern. There is some mixing between 'get_' and 'list_' for read operations, but overall the conventions are predictable and easy to follow.

    Tool Count2/5

    With 29 tools, this exceeds the 25-tool threshold for a 'too many' rating. While the scope is broad, the high count makes the surface feel heavy and increases selection complexity, even though each tool is well-scoped individually.

    Completeness4/5

    The server covers the full ticket lifecycle including comments, attachments, time tracking, views, and macros. Minor gaps exist such as lack of ticket deletion and user management, but core support workflows are well represented.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers