zammad-go-mcp

zammad-go-mcp

Zammad API にアクセスするための MCP サーバーです。

このサーバーでは、次のことができます。

• チケットとユーザーの一覧を読み取ります。
• 特定のチケットとユーザーの詳細を取得します。
• チケットとユーザーを検索します。
• 新しいチケットを作成します。
• 既存のチケットにメモ（記事）を追加します。
• チケットのコミュニケーション履歴（記事）を取得します。

機能

このサーバーは、次の MCP リソースとツールを公開します。

リソースを使用すると、URI を使って Zammad のデータを構造化された形式で AI が読み取れます。

• zammad://tickets
  • 名前： チケット一覧
  • 説明： 設定された API トークンでアクセス可能なすべてのチケットを一覧表示します。
  • MIME タイプ： application/json
• zammad://tickets/{ticket_id} （テンプレート）
  • 名前： チケットを表示（リソース）
  • 説明： {ticket_id} で指定された特定のチケットの詳細を表示します。
  • MIME タイプ： application/json
• zammad://users
  • 名前： ユーザー一覧
  • 説明： 設定された API トークンでアクセス可能なすべてのユーザーを一覧表示します。
  • MIME タイプ： application/json
• zammad://users/{user_id} （テンプレート）
  • 名前： ユーザーを表示（リソース）
  • 説明： {user_id} で指定された特定のユーザーの詳細を表示します。
  • MIME タイプ： application/json

ツール

ツールを使用すると、AI は Zammad 内で操作を実行したり、特定のクエリを実行したりできます。

• create_ticket：Zammad に新しいチケットを作成します。
  • 必須：title、group、customer（メールアドレスまたはユーザー ID）、body。
  • 任意：type（記事タイプ、デフォルト：「note」）、internal（ブール値、デフォルト：false）。
• search_tickets：クエリ文字列に基づいてチケットを検索します。
  • 必須：query。
  • 任意：limit（デフォルト：50）。
• add_note_to_ticket：既存のチケットに内部メモ（記事）を追加します。
  • 必須：ticket_id、body。
  • 任意：internal（ブール値、デフォルト：true）。
• get_ticket：ID で指定された特定のチケットの詳細を取得します。
  • 必須：ticket_id。
• get_user：ID で指定された特定のユーザーの詳細を取得します。
  • 必須：user_id。
• search_users：クエリ文字列（例：メールアドレス、ログイン名、名前）に基づいてユーザーを検索します。
  • 必須：query。
  • 任意：limit（デフォルト：50）。
• get_ticket_articles：特定のチケットのすべての記事（コミュニケーション）を取得します。
  • 必須：ticket_id。

前提条件

• Go： バージョン 1.24 以降がインストールされていること。
• Zammad インスタンス： 稼働中の Zammad インスタンス（URL）にアクセスできること。
• Zammad API トークン： Zammad インスタンス内で生成され、十分な権限を持つ API トークンがあること。

Zammad API トークンの取得

この MCP サーバーが API に対して認証を行い、操作できるようにするには、Zammad 内で API トークンを生成する必要があります。

1. 管理者アカウント（または API トークンを管理する権限を持つアカウント）で Zammad インスタンスにログインします。
2. プロフィール設定に移動します（通常は左下にあるアバターまたはイニシャルをクリックします）。
3. トークンアクセスセクションに移動します。
4. **「作成」**または該当するボタンをクリックして、新しいトークンを生成します。
5. トークンにわかりやすいラベル（例：「Claude MCP Server」）を付けます。
6. 必要な権限を割り当ててください。 提供されるツールに基づき、次のような権限が必要になります。
   • ticket.agent（または用途に応じて ticket.customer） - チケットの表示、作成、検索、および記事の追加に必要です。
   • user.reader - ユーザーの表示と検索に必要です。
   • （任意） admin.user は、より広範なユーザー検索や、後からこれらのツールを追加する場合の変更に必要となることがあります。詳細は Zammad の権限に関するドキュメントを確認してください。
7. **「作成」または「保存」**をクリックします。
8. 生成されたトークンをすぐにコピーします。 Zammad ではトークンが表示されるのは一度だけです。安全な場所に保管してください。

インストールとセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/arush15june/zammad-mcp-go.git
   cd zammad-mcp-go
   

2. バイナリをビルドします：

   go build -o zammad-mcp-go main.go
   

   これにより、カレントディレクトリに zammad-mcp-go（Windows の場合は zammad-mcp-go.exe）という名前の実行可能ファイルが作成されます。

Claude Desktop の設定

{
  "mcpServers": {
        "zammad": {
            "command": "<path-to>/zammad-go-mcp.exe",
            "args": [],
            "env": {
                "ZAMMAD_URL": "<zammad_url>",
                "ZAMMAD_TOKEN": "<zammad_token>"
            }
        }
    }
}