Zendesk MCP Server

Zendesk MCP サーバー

Claude などの AI アシスタントを Zendesk Support とシームレスに連携させる、Model Context Protocol（MCP）サーバーです。Zendesk チケットを自然言語で操作でき、会話型 AI を通じてサポートチケットの検索、作成、更新、管理を行えます。

✨ 特長

• 🎫 チケット管理のすべてに対応：Zendesk チケットの作成、取得、更新、検索
• 💬 コメントとメモ：公開コメントと非公開の内部メモを追加
• 🔍 高度な検索：Zendesk の強力なクエリ構文を使ってチケットを検索
• 🔗 インシデント管理：関連付けられたインシデントチケットを取得、管理
• 🏷️ タグ管理：チケットのタグとメタデータを追加、管理
• 🔒 安全な認証：安全にアクセスするため Zendesk API トークンを使用
• 🚀 簡単なインストール：npm、npx、または手動セットアップで利用可能

🚀 クイックスタート

オプション 1：NPM でインストール（推奨）

npm install -g zd-mcp-server

オプション 2：npx で使用（インストール不要）

npx zd-mcp-server

オプション 3：開発環境のセットアップ

git clone https://github.com/koundinya/zd-mcp-server.git
cd zd-mcp-server
npm install
npm run build

⚙️ 設定

環境変数

システムまたは MCP クライアントの設定で、以下の環境変数を設定します。

export ZENDESK_EMAIL="[email protected]"
export ZENDESK_TOKEN="your-zendesk-api-token"
export ZENDESK_SUBDOMAIN="your-company"  # from https://your-company.zendesk.com

Claude Desktop のセットアップ

Claude Desktop の設定ファイルに追加します。

場所：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

設定：

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

代替方法（グローバルにインストールした場合）：

{
  "mcpServers": {
    "zendesk": {
      "command": "zd-mcp-server",
      "env": {
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

Cursor IDE のセットアップ

~/.cursor/mcp.json、またはプロジェクト内の .cursor/mcp.json に追加します。

{
  "mcpServers": {
    "zendesk": {
      "command": "npx",
      "args": ["-y", "zd-mcp-server"],
      "env": {
        "ZENDESK_EMAIL": "[email protected]",
        "ZENDESK_TOKEN": "your-zendesk-api-token",
        "ZENDESK_SUBDOMAIN": "your-company"
      }
    }
  }
}

その他の MCP クライアント

その他の MCP 対応クライアント（Cline、Windsurf など）については、MCP サーバーの設定方法を各クライアントのドキュメントで確認してください。このサーバーは標準の MCP プロトコルに対応しています。

🛠️ 利用可能なツール

ツール	説明	使用例
zendesk_get_ticket	ID でチケットを取得	「チケット #12345 を取得して」
zendesk_get_ticket_details	コメントを含むチケットの詳細を取得	「チケット #67890 の詳細をすべて表示して」
zendesk_search	クエリ構文でチケットを検索	「先週の緊急チケットをすべて検索して」
zendesk_create_ticket	新しいチケットを作成	「ログインの問題について、優先度の高いチケットを作成して」
zendesk_update_ticket	チケットのプロパティを更新	「チケット #555 のステータスを解決済みにして」
zendesk_add_private_note	エージェント向けの内部メモを追加	「調査の進捗について非公開メモを追加して」
zendesk_add_public_note	顧客向けの公開コメントを追加	「解決手順を顧客に返信して」
zendesk_get_linked_incidents	問題に関連付けられたインシデントチケットを取得	「この問題チケットに関連するインシデントを表示して」

💬 使用例

設定が完了したら、AI アシスタントに自然な言葉で依頼できます。

チケット管理

"Show me all high priority tickets assigned to me"
"Create a new ticket: Customer can't access dashboard, priority urgent"
"Update ticket #12345 status to pending and add a note about waiting for customer response"

検索と調査

"Find all solved tickets from this week tagged with 'billing'"
"Search for open tickets containing 'password reset'"
"Show me tickets created by [email protected] in the last 30 days"

顧客とのコミュニケーション

"Add a public comment to ticket #789: 'We've identified the issue and working on a fix'"
"Add a private note: 'Customer confirmed the workaround is effective'"

高度なクエリ

"Find all problem tickets that have linked incidents"
"Show me escalated tickets that haven't been updated in 2 days"
"Get details for ticket #456 including all comments and history"

🔑 認証の設定

1. API トークンを生成する

1. Zendesk アカウントにログインします
2. Admin Center → Apps and integrations → APIs → Zendesk API に移動します
3. Add API token をクリックします
4. 説明に「MCP Server Integration」と入力します
5. Create をクリックし、トークンをコピーします
6. 重要：このトークンは再表示できないため、安全な場所に保存してください

2. サブドメインを確認する

Zendesk の URL 形式：https://YOUR-SUBDOMAIN.zendesk.com YOUR-SUBDOMAIN を ZENDESK_SUBDOMAIN の値として使用します。

3. 必要な権限

Zendesk ユーザーアカウントに次の権限があることを確認してください。

• Agent ロール（最低限）
• Ticket access 権限
• API access が有効

🔧 開発

プロジェクト構成

zd-mcp-server/
├── src/
│   ├── index.ts          # Server entry point
│   └── tools/
│       └── index.ts      # Zendesk tool implementations
├── dist/                 # Compiled JavaScript
├── package.json
├── tsconfig.json
└── README.md

ソースからビルド

git clone https://github.com/koundinya/zd-mcp-server.git
cd zd-mcp-server
npm install
npm run build

ローカルで実行

# Start the server
npm start

# Development mode with auto-rebuild
npm run dev

テスト

# Test with MCP Inspector (if available)
npx @modelcontextprotocol/inspector zd-mcp-server

# Or test the built version
npx @modelcontextprotocol/inspector node dist/index.js

🔍 トラブルシューティング

よくある問題

❌ 「Authentication failed」エラー

• API トークンが正しく、有効期限が切れていないことを確認してください
• メールアドレスが Zendesk アカウントのものと一致していることを確認してください
• サブドメインのスペルが正しいことを確認してください（.zendesk.com のサフィックスは付けません）

❌ 「Permission denied」エラー

• Zendesk ユーザーにエージェント以上の権限があることを確認してください
• アカウントで API アクセスが有効になっていることを確認してください
• トークンに必要なスコープがあるか確認してください

❌ 「Server not found」エラー

• パッケージをインストールしたことを確認してください：npm install -g zd-mcp-server
• 代わりに npx を使ってみてください：npx zd-mcp-server
• MCP クライアントの設定ファイルの構文が正しいことを確認してください

❌ 「Environment variables not set」エラー

• 3 つすべての環境変数が設定されていることを確認してください：ZENDESK_EMAIL、ZENDESK_TOKEN、ZENDESK_SUBDOMAIN
• 環境変数を設定した後、MCP クライアントを再起動してください
• 環境変数名にタイプミスがないか確認してください

デバッグモード

デバッグログを有効にします：

DEBUG=zd-mcp-server:* zd-mcp-server

ログファイル

MCP クライアントのログを確認します：

• Claude Desktop：~/Library/Logs/Claude/（macOS）または %APPDATA%/Claude/logs/（Windows）
• Cursor：出力パネルで MCP サーバーのログを確認します
• ターミナル：サーバーを直接実行して、リアルタイムのログを確認します

📚 高度な使い方

検索クエリの構文

Zendesk 検索は、強力なクエリ演算子に対応しています：

# Status-based searches
status:open status:pending status:solved

# Priority searches  
priority:urgent priority:high priority:normal priority:low

# Date-based searches
created>2024-01-01 updated<2024-01-31

# Tag searches
tags:billing tags:technical-issue

# Requester searches
requester:[email protected]

# Complex combinations
status:open priority:high created>2024-01-01 tags:billing

一括操作

サーバーは一括操作を直接サポートしていませんが、コマンドを連結できます：

"Search for all urgent tickets, then show me details for the first 3 results"
"Find tickets tagged 'billing', update them to normal priority, and add a note about the billing system maintenance"

🤝 コントリビューション

コントリビューションを歓迎します！お気軽にプルリクエストを送信してください。

開発環境のセットアップ

1. リポジトリをフォークします
2. フィーチャーブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

問題の報告

バグを見つけた場合は、次の情報を添えて Issue を作成してください：

• 問題の説明
• 再現手順
• 期待される動作
• お使いの環境（OS、Node.js のバージョン、MCP クライアント）
• 関連するログ出力

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。

🔗 リンク

• GitHub：https://github.com/koundinya/zd-mcp-server
• npm：https://www.npmjs.com/package/zd-mcp-server
• Zendesk API ドキュメント：https://developer.zendesk.com/api-reference/
• Model Context Protocol：https://modelcontextprotocol.io/

🆘 サポート

• Issue：GitHub Issues
• Zendesk API：Zendesk 開発者向けドキュメント
• MCP プロトコル：MCP ドキュメント

---

MCP と Zendesk のコミュニティのために ❤️ を込めて作成しました