zendesk-mcp

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

機能

• Zendeskチケット、コメント、添付ファイルの検索と取得

• 公開返信および内部メモの投稿

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

• 作業時間記録の読み書き

• チケットをトラッカー（GitLab、GitHub、Jira）への引き継ぎ用Markdown形式のイシュードラフトとしてフォーマット

• （オプション）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 をリクエストしてください。

インストール

プロジェクトローカルの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/... を介して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統合 を参照

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

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

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_comments",
      "mcp__zendesk__zendesk_list_attachments",
      "mcp__zendesk__zendesk_download_attachment",
      "mcp__zendesk__zendesk_search_tickets",
      "mcp__zendesk__zendesk_ticket_to_gitlab_context"
    ]
  }
}

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

ツール

オプション: 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 は「設定されていません」というメッセージを返します。

開発

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 を参照）。

ライセンス

Apache-2.0