zendesk-mcp
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以下の入力を求められます:
Zendesk サブドメイン(例:
acme(acme.zendesk.comの場合))管理者が作成した OAuth クライアント ID
OAuth クライアントシークレット
(オプション)Git-Zen 統合フィールド ID — オプション: Git-Zen 統合 を参照
(オプション)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 が呼び出しごとに確認を求めます。
ツール
チケット
ツール | 機能 |
| ステータス、優先度、タイプ、担当者、リクエスター、タグ、キーワードでチケットを検索 |
| ページングと並べ替えに対応したチケット一覧(page、per_page、sort_by、sort_order) |
| 1 件のチケットのメタデータを取得 |
| 新規チケットを作成(件名、説明、オプションで優先度/タイプ/担当者 ID/リクエスター ID/タグ/カスタムフィールド) |
| 既存チケットの 1 つ以上のフィールドを更新(ステータス、優先度、件名、タイプ、担当者 ID、リクエスター ID、グループ ID、カスタムステータス ID、タグ、カスタムフィールド、期日) |
| チケットの会話スレッドを取得 |
| チケットの添付ファイル一覧を取得 |
| 添付ファイルをローカルのキャッシュディレクトリにダウンロード |
| チケットとその会話を Markdown の issue ドラフトに整形 |
| チケットに公開返信を投稿 |
| チケットにエージェント専用の内部メモを投稿 |
| チケットステータスを設定( |
| チケットをメールアドレスまたは |
タグ
ツール | 機能 |
| チケットにタグを追加(冪等) |
| チケットからタグを削除(冪等) |
ビューとマクロ
ツール | 機能 |
| 有効なすべてのビューを一覧表示 |
| ビューのフィルター条件と実行設定を取得 |
| ビューに現在一致するチケットを取得 |
| アクション付きの有効なマクロを一覧表示 |
| マクロが行う変更をプレビュー |
| マクロをチケットに適用(フィールド変更を適用し、コメントがあれば投稿) |
ユーザー、グループ、組織
ツール | 機能 |
| 名前またはメールアドレスでユーザーを検索 |
| 有効なすべてのグループを一覧表示 |
| グループのメンバーを一覧表示 |
| カスタムフィールドを含む組織を取得 |
| すべてのカスタムチケットステータスとその ID を一覧表示 |
時間追跡
ツール | 機能 |
| チケットの時間追跡エントリを読み取り |
| チケットに時間エントリを記録 |
Git-Zen 統合
ツール | 機能 |
| (Git-Zen のみ)チケットにリンクされた GitLab の issue / MR / commit を取得 |
プロンプト
サーバーは 2 つの MCP プロンプトを公開しており、一部のクライアント(例: Claude Desktop)ではスラッシュコマンドとして表示されます:
プロンプト | 引数 | 機能 |
|
| モデルにチケットを取得させ、要約、ステータス/タイムライン、主要なやり取りのポイントを生成させる |
|
| モデルにチケットを取得させ、顧客向けの返信ドラフトを作成させる(投稿前に確認ステップあり) |
オプション: 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ライセンス
Available Tools
29 toolszendesk_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_git_zen_linksA
Get linked GitLab issues, merge requests, and commits for a Zendesk ticket via the Git-Zen integration. Returns structured lists with state, labels, weight, and direct GitLab links.
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
Scored across 29 tools
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.
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.
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.
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
Related MCP Connectors
Read tickets, users, orgs, macros and satisfaction ratings; create, update and comment on tickets.
Search and read Zammad tickets, customers and organizations; add notes, replies and ticket updates.
Read tickets, contacts, companies, agents and groups; create, update and reply to tickets.
Work with Enchant help desk tickets: list, read, reply, add notes and labels, manage customers.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with Zendesk to manage tickets, retrieve ticket fields, comments, and priority based on SLA, as well as get unsolved tickets by agent name.1-
- FlicenseNot gradedqualityAmaintenanceEnables users to fetch, create, and update Zendesk tickets and comments, analyze tickets and draft responses, and query Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables integration with Zendesk to retrieve and manage tickets and comments, analyze tickets, draft responses, and access Help Center articles as a knowledge base.-
- FlicenseNot gradedqualityAmaintenanceEnables retrieving and managing Zendesk tickets and comments, accessing Help Center articles as a knowledge base, and using specialized prompts for ticket analysis and response drafting.-