Zammad Mcp Server

Zammad MCP Server — Claude、Cursor、LLM を Zammad のヘルプデスクに接続

Zammad MCP Server は、オープンソースのヘルプデスクおよびチケットシステムである Zammad 向けの、無料でオープンソース、かつ本番環境に対応した Model Context Protocol（MCP） サーバーです。AI アシスタント（Claude Desktop、Cursor、および MCP 対応の LLM エージェント）を Zammad インスタンスに直接接続し、自然言語でチケットの検索、スレッドの要約、返信の下書き、ユーザーや組織の管理を行えます。

ひと言で言うと： uvx zammad-mcp-server を使うと、Zammad のヘルプデスクが、あらゆる AI エージェントから呼び出せる型付きツール群に変わります。Zammad プラグインも、カスタム REST 接続コードも不要です。

⭐ 役に立ちましたか？ リポジトリにスターを付けてください — 他の Zammad チームがこのプロジェクトを見つけやすくなり、ロードマップの策定にも役立ちます。

目次

• 概要
• Zammad MCP Server を使う理由
• 主な機能
• Zammad の互換性
• ドキュメント
• クイックスタート
• Zammad Commander（ブラウザー用チャット UI）
• 利用可能な MCP ツール
• アクセス制御とセキュリティ
• 認証方法
• アーキテクチャ
• ホスティングとデプロイの選択肢
• FAQ
• コントリビューション
• ライセンス

概要

Zammad MCP Server を使うと、Claude などの AI アシスタントが、Model Context Protocol を介して Zammad のチケットシステム機能に構造化された型安全な方法でアクセスできます。Model Context Protocol は、LLM を外部のツールやデータに接続するためのオープン標準です。UI をスクレイピングしたり、チケットのテキストをチャットウィンドウに貼り付けたりする代わりに、アシスタントは独立した検証済みのツール（search_tickets、get_ticket_articles、create_article など 30 以上）を呼び出し、スキーマで検証された整ったデータを受け取ります。

これにより、自然言語でやり取りしながら、AI によるチケット管理、カスタマーサポートの自動化、ヘルプデスクのレポート作成が可能になります。データはお客様の Zammad インスタンスとお客様の MCP クライアント内に保持されます。

Zammad MCP Server を使う理由

大規模言語モデルを実際のヘルプデスクに接続するには、通常、Zammad REST API との専用連携を作成し、認証を処理し、役立つ回答をひとつ得る前にアクセス制御を一から構築する必要があります。このサーバーは、そうした手間を取り除きます。

• Claude や Cursor からヘルプデスクに話しかける — 「チケット 4821 を要約して」「Support キューの未解決チケットを一覧表示して」「この顧客への返信を下書きして」。
• トリアージとレポート作成 — エージェントに受信チケットの分類、優先順位付け、要約を任せたり、分析用に get_ticket_stats を呼び出したりできます。
• デフォルトで安全 — 環境変数で設定できるきめ細かなアクセス制御により、本番環境で読み取り専用にしたり、破壊的なツール（delete_ticket、delete_user）を無効にしたりできます。
• 一度の連携ですべてのクライアントに対応 — MCP 向けに一度連携を実装すれば、Claude Desktop、Cursor、カスタムエージェントスタックで利用できます。
• ベンダーロックインなし — MIT ライセンスでセルフホスト可能。REST API を介してあらゆる Zammad 6.0+／7.x インスタンスで動作し、Zammad 側のプラグインは不要です。

主な機能

• 包括的な API カバレッジ：チケット、ユーザー、組織、グループなどにフルアクセスできます
• 高度なアクセス制御：カテゴリ単位およびツール単位の制限によるきめ細かな権限管理
• 本番環境対応：FastMCP、Pydantic、最新の Python 開発手法を用いて構築されています
• 柔軟な認証：API トークン、OAuth2、基本認証に対応しています
• スマートキャッシュ：静的データ（グループ、状態、優先度）をインテリジェントにキャッシュします
• 型安全：Pydantic モデルとランタイム検証を全面的に採用しています
• 拡張可能：新しいツールやインテグレーションを簡単に追加できます
• 十分にテスト済み：カバレッジ 90％以上の包括的なテストスイートを備えています

Zammad との互換性

MCP サーバーは REST API を介して Zammad と通信します。Zammad 側にプラグインを 追加する必要はありません。完全な対応表は docs/COMPATIBILITY.md をご覧ください。

Zammad のバージョン	状態
7.1	テスト済み（主な対象；デフォルトの開発スタック）
7.0	テスト済み
6.5.x	互換性あり
6.0 – 6.4.x	互換性あり（サポート対象の最低バージョン）
< 6.0	サポート対象外

MCP パッケージと Zammad： PyPI の zammad-mcp-server は独立したバージョン番号（0.1.x）を使用しています。1 つの MCP リリースで、サポート対象のすべての Zammad バージョンに対応します。ZAMMAD_URL にインスタンスの URL を設定してください。Zammad のバージョンごとに MCP をビルドする必要はありません。

ローカル開発スタック： docker/ では、デフォルトで Zammad 7.1 を使用します。docker/.env の ZAMMAD_VERSION を変更すると上書きできます（7.0、6.5、6.3 にも対応しています）。詳細は docker/README.md をご覧ください。

Zammad 7.x では、Zammad 側で PostgreSQL が必要です（7.0 以降、MySQL はサポートされていません）。 同梱の開発スタックでは PostgreSQL を使用します。

ドキュメント

詳細なガイド、セキュリティチェックリスト、デプロイに関する注意事項は、Open Ticket AI のウェブサイトに掲載されています。

ページ	内容
Zammad MCP Server（概要）	対象ユーザーと、Zammad および AI のエコシステムにおける位置付け
クイックスタート	数分でインストールし、health_check を実行する方法
Claude と Cursor のセットアップ	MCP クライアントの設定
設定	環境変数とアクセス制御ポリシー
ツールリファレンス	カテゴリ別の全 MCP ツール
セキュリティ	トークン、最小権限、本番環境向けチェックリスト
デプロイ	Docker、SSE、本番環境に関する注意事項
Zammad との互換性（GitHub）	サポート対象の Zammad バージョンと開発スタックのタグ
Zammad Commander（GitHub）	LibreChat + MCP + お使いの Zammad — 社内管理者向けチャット

チュートリアル： Zammad MCP Server — セットアップと使い方（ブログ）

ドイツ語： Zammad MCP Server ドキュメント · セットアップと使い方（ブログ）

Zammad と AI のエコシステムにおける位置づけ

• Zammad 7.1 ネイティブ AI — Zammad の UI に組み込まれた要約機能と文章作成アシスタントです。
• Zammad MCP Server（このプロジェクト） — 外部の MCP クライアント（Claude Desktop、Cursor、カスタムエージェント）を Zammad に接続します。
• Zammad Commander — ブラウザーチャット UI（LibreChat ＋ この MCP サーバー ＋ お使いの Zammad）です。Cursor は不要で、docker compose up で社内管理者向けチャットを利用できます。Zammad Commander（ブラウザーチャット UI）をご覧ください。
• Open Ticket AI Runtime — OTAI Zammad コネクターを通じて、カスタム学習済みモデルでオンプレミス推論を実行します（連携ガイド）。

3 つすべてを併用できます。MCP は「Claude からヘルプデスクに話しかける」ための最速の方法です。IDE ではなくチームチャット UIをお探しですか？ **Zammad Commander**をお使いください。キューでカスタムモデルが必要な場合は、Open Ticket AI for Zammadをご覧ください。

クイックスタート

手順を追ったガイド：クイックスタートガイド

インストール

PyPI から（MCP クライアントに推奨）：

pip install zammad-mcp-server
# or
uv tool install zammad-mcp-server
# or run once without installing
uvx zammad-mcp-server

ソースから（開発用）：

git clone https://github.com/Softoft-Orga/zammad-mcp-server.git
cd zammad-mcp-server
uv sync --extra dev

設定

すべての環境変数とアクセス ポリシーについては、設定ガイドをご覧ください。

.env ファイルを作成します。

ZAMMAD_URL=https://your-zammad-instance.com
ZAMMAD_HTTP_TOKEN=your_api_token_here

# Optional: Access control
MCP_ALLOWED_CATEGORIES=all
MCP_DENIED_TOOLS=delete_ticket,delete_user

サーバーの実行

# Run with stdio transport (for Claude Desktop)
zammad-mcp-server

# Run with Streamable HTTP (Docker / remote clients; recommended)
zammad-mcp-server --transport http --host 0.0.0.0 --port 8000

# Legacy SSE transport (older MCP clients)
zammad-mcp-server --transport sse --host 0.0.0.0 --port 8000

Claude Desktop / Cursor

クライアントの完全な設定手順：Claude & Cursor の設定

claude_desktop_config.json または Cursor の Settings → MCP に追加します。

{
  "mcpServers": {
    "zammad": {
      "command": "uvx",
      "args": ["zammad-mcp-server"],
      "env": {
        "ZAMMAD_URL": "https://your-zammad-instance.com",
        "ZAMMAD_HTTP_TOKEN": "your_token",
        "MCP_DENIED_TOOLS": "delete_ticket,delete_user,delete_organization"
      }
    }
  }
}

保存後、アプリを再起動します。「Zammad で health_check を実行して」または「未解決のチケットを一覧表示して」と尋ねてみてください。

Zammad Commander（ブラウザーチャット UI）

すべてのエージェントが Cursor や Claude Desktop を使いたいとは限りません。Zammad Commanderは公式のコンパニオンプロジェクトです。Docker Compose によってLibreChat、この MCP サーバー（Streamable HTTP サイドカー）、お使いの Zammadがまとめて起動するため、サポートリーダーは検索、要約、返信の下書きに使えるブラウザーチャットを利用できます（人間が介在する運用 — 自動送信は行われず、削除はデフォルトで拒否されます）。

git clone https://github.com/Softoft-Orga/zammad-commander.git
cd zammad-commander
cp env.example .env
# Set ZAMMAD_URL, ZAMMAD_HTTP_TOKEN, and LibreChat secrets.

docker compose up -d
# On-prem LLM: add -f docker-compose.onprem.yml (see Commander README).

http://localhost:3080**を開き、**Zammad Commanderを選んでチャットを始めます。

必要な情報	場所
セットアップ全般（OpenRouter と Ollama の比較、デモ用 Zammad、ハードウェア）	Commander README
MCP 側からの手順	docs/ZAMMAD_COMMANDER.md
Commander が使用する MCP 環境変数／拒否リスト	設定ガイド

開発環境

ローカル開発用に、Docker Compose の完全なセットアップを用意しています。デフォルトは Zammad 7.1です。他のサポート対象タグを使用する場合は、docker/.env で ZAMMAD_VERSION を設定してください。docker/README.mdをご覧ください。

cd docker
docker-compose up -d

# Wait for services to start (may take 2-3 minutes)
docker-compose ps

# Access Zammad at http://localhost:8080
# Default credentials: [email protected] / admin

テストの実行

# Run all tests
pytest

# Run with coverage
pytest --cov=zammad_mcp_server --cov-report=html

# Run specific test file
pytest tests/test_models.py -v

利用可能な MCP ツール

このサーバーは Zammad 用の型付き MCP ツールを 35 個提供します。完全なリファレンス：ツールリファレンス

チケット

• get_ticket - チケットの詳細を取得
• search_tickets - フィルターを使って検索
• create_ticket - 新しいチケットを作成
• update_ticket - チケットのプロパティを更新
• delete_ticket - チケットを削除（管理者）
• get_ticket_articles - すべてのメッセージを取得
• create_article - 返信／メモを追加
• get_ticket_stats - 分析と指標を取得
• get_ticket_states - 利用可能な状態の一覧を取得
• get_priorities - 優先度レベルの一覧を取得
• list_ticket_tags / add_ticket_tag / remove_ticket_tag - チケットのタグ
• get_article_attachment - 記事のファイルをダウンロード
• link_tickets / merge_tickets - チケットを関連付けまたは統合
• summarize_ticket - エージェント向けのプレーンテキストのスレッドとタグ

ユーザー

• get_user - ユーザーの詳細を取得
• search_users - ユーザーを検索
• create_user - 新しいユーザーを追加
• update_user - ユーザーのプロパティを変更
• delete_user - ユーザーを削除（管理者）
• get_current_user - 認証済みユーザーを取得

組織

• get_organization - 組織の詳細を取得
• search_organizations - 組織を検索
• create_organization - 組織を追加
• update_organization - 組織を変更
• delete_organization - 組織を削除（管理者）

グループ

• get_group - グループの詳細を取得
• list_groups - すべてのグループを一覧表示
• create_group - グループを作成

タグ（管理者カタログ）

• list_tags - 全体のタグ一覧

システム

• health_check - サーバーの状態を確認
• get_server_info - Zammad のバージョン／情報を取得
• get_allowed_tools - アクセス可能なツールを一覧表示

アクセス制御とセキュリティ

このサーバーには、本番環境の Zammad に AI エージェントを安全に接続できる高度なアクセス制御システムが含まれています。本番環境への導入チェックリスト：セキュリティガイド

権限レベル

• DENIED - ツールに一切アクセスできません
• READ_ONLY - 表示のみ可能で、変更はできません
• WRITE - データの読み取りと変更が可能です
• ADMIN - 削除を含むすべての操作が可能です

環境変数による設定

# Allow all categories (default)
MCP_ALLOWED_CATEGORIES=all

# Allow specific categories only
MCP_ALLOWED_CATEGORIES=tickets,groups,system

# Deny specific dangerous tools
MCP_DENIED_TOOLS=delete_ticket,delete_user,delete_organization

# Restrict to specific groups (reads and writes)
MCP_ALLOWED_GROUPS=Support,Sales

# Restrict to organization IDs
MCP_ALLOWED_ORGANIZATIONS=1,2

# Read-only preset (no creates/updates/deletes)
MCP_DEFAULT_PERMISSION=read_only

# Rate limit (0 disables)
MCP_RATE_LIMIT_PER_MINUTE=60

プログラムによるアクセス制御

from zammad_mcp_server.access_control import AccessController, AccessPolicy, Permission, ToolCategory

# Create custom policy
policy = AccessPolicy(
    default_permission=Permission.READ_ONLY,
    category_permissions={
        ToolCategory.TICKETS: Permission.WRITE,
        ToolCategory.ADMIN: Permission.DENIED,
    },
    denied_tools={"delete_ticket"},
)

controller = AccessController(policy)

アーキテクチャ

詳細な技術ドキュメントについては、ARCHITECTURE.md を参照してください。

┌─────────────────┐     ┌─────────────────┐
│  Claude/AI      │     │  MCP Client     │
│  Assistant      │────▶│  (Claude App)   │
└─────────────────┘     └────────┬────────┘
                                 │ MCP Protocol
                        ┌────────▼────────┐
                        │   MCP Server    │
                        │  (FastMCP)      │
                        ├─────────────────┤
                        │  Access Control │
                        │  Tools          │
                        │  Resources      │
                        └────────┬────────┘
                                 │ HTTP/REST
                        ┌────────▼────────┐
                        │  Zammad Client  │
                        │  Wrapper        │
                        └────────┬────────┘
                                 │
                        ┌────────▼────────┐
                        │  Zammad API     │
                        │   Instance      │
                        └─────────────────┘

認証方法

サーバーは 3 種類の認証方法に対応しています。詳細：設定 — 認証

1. API トークン（推奨）

ZAMMAD_HTTP_TOKEN=your_token_here

Zammad でトークンを作成します：プロフィール → トークンアクセス

2. OAuth2 トークン

ZAMMAD_OAUTH2_TOKEN=your_oauth_token

3. ユーザー名／パスワード

[email protected]
ZAMMAD_PASSWORD=your_password

リソース

サーバーは複数の MCP リソースを公開します：

• zammad://ticket/{id} - 記事を含む、書式設定済みのチケット
• zammad://user/{id} - ユーザーの詳細
• zammad://config/states - 利用可能なチケットの状態
• zammad://config/priorities - 利用可能な優先度
• zammad://organization/{id} - 組織のスナップショット

プロンプト

一般的なワークフロー向けの組み込みプロンプト：

• ticket_summary_prompt - チケットの要約を生成
• customer_communication_prompt - 顧客への返信文を作成
• escalation_analysis_prompt - エスカレーションの必要性を分析
• analyze_ticket - タグと SLA のヒントを含む構造化分析
• draft_response - ロケールに応じた顧客向けまたは社内向けの返信
• triage_queue - グループ内の未解決チケットに優先順位を付ける
• escalation_summary - 期限超過／クローズ保留の概要

ホスティングの選択肢

Zammad MCP Server は複数の方法でホストできます：

1. ローカル開発

zammad-mcp-server

2. Docker コンテナ

公開済みイメージは GitHub Container Registry（ghcr.io）にあります：

docker pull ghcr.io/softoft-orga/zammad-mcp-server:latest

docker run -p 8000:8000 \
  -e ZAMMAD_URL=https://your-zammad.com \
  -e ZAMMAD_HTTP_TOKEN=your_token \
  ghcr.io/softoft-orga/zammad-mcp-server:latest

# Override to legacy SSE if needed:
# docker run ... ghcr.io/softoft-orga/zammad-mcp-server:latest \
#   zammad-mcp-server --transport sse --host 0.0.0.0 --port 8000

ローカルでビルドする：

docker build -t zammad-mcp-server .
docker run -p 8000:8000 -e ZAMMAD_URL=$ZAMMAD_URL zammad-mcp-server

3. クラウドへのデプロイ

Docker、SSE、本番環境でのホスティング（Google Cloud Run、Railway、Fly.io など）については、デプロイガイドを参照してください。

よくある質問

Zammad MCP サーバーとは何ですか？

Zammadのヘルプデスクを、AI アシスタント向けの型付きツールとして公開するオープンソースのModel Context Protocolサーバーです。MCP クライアント（Claude Desktop、Cursor、カスタムエージェントなど）から、自然言語で Zammad のチケット、ユーザー、組織を読み取り、操作できます。

Claude や Cursor を Zammad に接続するにはどうすればよいですか？

パッケージをインストールし、MCP クライアントの設定にZAMMAD_URLとZAMMAD_HTTP_TOKENを追加します。最も手早い方法はuvx zammad-mcp-serverです。クイックスタートとClaude および Cursor のセットアップガイドをご覧ください。

対応している Zammad のバージョンはどれですか？

Zammad 7.1（主な対象、テスト済み）、7.0（テスト済み）、6.0–6.5.x（互換性あり）に対応しています。Zammad とは REST API 経由で通信するため、Zammad 側のプラグインは不要です。互換性マトリックスをご覧ください。

本番環境の Zammad インスタンスで安全に使用できますか？

はい。アクセスは環境変数で制御できます。カテゴリを制限する（MCP_ALLOWED_CATEGORIES）、破壊的なツールを拒否する（MCP_DENIED_TOOLS=delete_ticket,delete_user）、または完全な読み取り専用で実行できます。本番環境で運用を開始する前に、セキュリティガイドをご確認ください。

Zammad MCP サーバーは無料でオープンソースですか？

はい。MIT ライセンスで、無料でセルフホストできます。SaaS への依存はなく、チケットデータは Zammad インスタンスと MCP クライアント内に保持されます。

Zammad に組み込まれている AI とはどう違いますか？

Zammad 7.1 に組み込まれた AI は、Zammad の UI 内で要約機能と文章作成アシスタントを提供します。一方、Zammad MCP サーバーは外部のAI エージェントを Zammad に接続します。Zammad と AI の全体像における位置付けをご覧ください。

Docker で実行できますか？

はい。ホスティングの選択肢と、Docker、SSE、クラウドホスティング（Cloud Run、Railway、Fly.io）についてのデプロイガイドをご覧ください。

Zammad Commander とは何ですか？

Zammad Commanderは、LibreChat、この MCP サーバー、Zammad を組み合わせて、docker compose upひとつで実行できる別の MIT ライセンスプロジェクトです。Claude Desktop や Cursor の代わりに、サポートチームのリーダーがブラウザーのチャット UIを必要とする場合にご利用ください。セットアップ方法：docs/ZAMMAD_COMMANDER.md。

コントリビューション

コントリビューションを歓迎します！ガイドラインについてはCONTRIBUTING.mdをご覧ください。

開発ワークフロー

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更を加えます
4. テストを実行します（pytest）
5. コミットします（git commit -m 'Add amazing feature'）
6. プッシュします（git push origin feature/amazing-feature）
7. プルリクエストを作成します

ロードマップ

• リアルタイム更新のための WebSocket サポート
• チケットの購読と通知システム
• Elasticsearch 統合による高度な検索
• マルチテナントサポート
• 監査ログ
• カスタムツールプラグイン
• GraphQL API サポート
• Webhook 統合

ライセンス

このプロジェクトは MIT ライセンスで提供されています。詳細はLICENSEをご覧ください。

サポート

• 📖 ドキュメント（英語） · ドキュメント（ドイツ語）
• 📘 セットアップチュートリアル（ブログ）
• 🐛 課題トラッカー
• 💬 ディスカッション

謝辞

• James Lowin によるFastMCPを使用して構築
• Model Context Protocolに着想を得ています
• Zammad — 素晴らしいオープンソースのヘルプデスク

関連プロジェクト

• Zammad Commander — LibreChat + この MCP サーバー + お使いの Zammad（MIT、Docker Compose）
• Zammad - チケットシステム本体
• zammad-py - Python クライアントライブラリ

---

❤️ を込めて Open Ticket AI が作成