Tickiti

tickiti-mcp

Claude などの AI アシスタントに Tickiti ヘルプデスク API を公開する MCP（Model Context Protocol）サーバーです。Tickiti Public API v1（/api/v1/...）を薄くラップしており、各 MCP ツールは v1 エンドポイントに転送し、ベアラートークンを追加します。また、書き込みの場合は冪等性キーも追加します。セキュリティ境界となるのはトークンの権限です。このサーバーは呼び出しを中継するだけで、権限を拡大することはないため、読み取り専用トークンを使えばアシスタントも読み取り専用になります。

📖 詳細なドキュメント：https://www.tickiti.com/docs/topic/mcp_server/

ツール

チケットツールには、検証済みの入力がすべて揃っています。その他の API には、汎用ツールが 2 つ用意されているため、エンドポイントごとに個別のツールを用意しなくても、API 全体を利用できます。

チケット

ツール	権限	用途
create_ticket	tickets:write	担当者、優先度、ステータス、参加者を指定してチケットを作成します（件名と内容、テンプレート、または対応内容を使用）。is_public は必須です
respond_to_ticket	tickets:write	返信を投稿します。ステータス、保留、担当者、優先度、キュー、件名、参加者を変更できます。返信全体をメールで送信するには send_full_email を指定します
close_ticket	tickets:write	チケットをクローズします。最終返信と解決内容を任意で指定できます
edit_response	tickets:write	通知せずに返信を直接変更します（本文全体、検索と置換、公開範囲）。または、社内メモを公開して通知します
delete_response	tickets:write	返信を論理削除します
add_participants / remove_participants	tickets:write	参加者を変更します
delete_tickets / restore_ticket	tickets:write	チケットを削除します（番号を指定するか、1 人の送信者からのチケットをすべて削除できます）。また、削除を取り消します
merge_tickets	tickets:write	2 件のチケットを統合します（古い方が残ります）
link_tickets / unlink_tickets / list_linked_tickets	tickets:write / read	「リンク済み」パネル
move_responses / copy_responses / split_ticket	tickets:write	スレッドを修正します。返信を移動またはコピーするか、返信を切り分けて新しいリンク済みチケットを作成します
change_originator	tickets:write	チケットを起票した人を変更します
delete_attachment	tickets:write	添付ファイルを 1 件削除します（悪意のあるファイルなど）。削除した記録は保持されます
get_ticket / list_responses	tickets:read	チケットのスレッド、参加者、リンクを取得します。長いメールスレッドを小さく保つには fields / max_body_chars を指定します
get_response	tickets:read	ID で指定した返信を 1 件取得します
query_tickets	tickets:read	チケットを検索します
query_responses / export_responses	tickets:read	チケットを横断して返信を取得します。件数とグループ別集計、NDJSON のディスクへのエクスポートもできます
get_attachment / download_attachment	tickets:read	添付ファイルのバイトデータを取得します（ダウンロードではサイズを問わずファイルにストリーミングします）
list_queues / list_teams / list_staff / list_resolutions / get_search_modes	tickets:read	キュー名と設定、チームキー、スタッフのアドレス、解決カテゴリ、検索用語を取得します

設定、テンプレート、メール、管理

ツール	権限	用途
list_perspectives / get_perspective	settings:read	条件と並べ替え順を含む保存済みビュー
list_watchlists	settings:read	ウォッチリスト
list_stock_responses / get_stock_response	settings:read	定型回答（検索、本文）
create_stock_response / update_stock_response / delete_stock_response	settings:write	定型回答の編集
get_template / search_templates / render_template	templates:read	テンプレートとよくある質問。送信せずにデータに適用してレンダリング
create_template / update_template	templates:write	テンプレートの編集（更新されるのは指定したフィールドのみです）
upload_template_image	templates:write / settings:write	テンプレートまたは定型回答用の画像をアップロード
send_email / search_sent_mail	mail:write / mail:read	メールの送信、送信済みメールの検索
list_api_tokens / create_api_token / update_api_token / revoke_api_token	administration:*	API キー（トークンで許可されるのは、そのトークンが持つ権限のみです）
list_workflow	workflow:read	解決カテゴリ、介入、エスカレーション
run_report	reports:read	分析レポート
get_token_info	any	このトークンでできること：権限、所有者のロール、プラン
list_instances	—	設定済みの Tickiti インスタンス（下記参照）
list_endpoints	—	権限、パス、本文パラメーターを含むすべての API エンドポイント
tickiti_call	エンドポイントごと	ファミリーとアクションを指定して、任意の /api/v1 エンドポイントを呼び出す

名前付きツールの範囲を超える機能（メール、テンプレート、ワークフローの書き込み、管理、 スーパーバイザー）については、アシスタントは list_endpoints でアクションを特定し、 続いて tickiti_call で実行します。これにより、v1 API 全体を利用できます。

要件

• Node.js 20 以降
• Tickiti API トークン。Administration → API keys から発行し、アシスタントに付与する権限を設定します
• MCP 対応クライアント。例：Claude Code または Claude デスクトップアプリ

インストール

git clone https://github.com/tickiti/tickiti-mcp.git
cd tickiti-mcp
npm install
npm run build

ビルド済みサーバーは dist/server.js です。

設定

サーバーは2つの環境変数を読み取ります（いずれかが設定されていない場合、起動時に直ちに失敗します）。

変数	用途
TICKITI_API_BASE	Tickiti インストール環境の公開アドレス。末尾にスラッシュは付けません。例：https://support.example.com。サーバーが /api/v1/… を付加します。
TICKITI_API_TOKEN	ベアラートークン。その権限によって、アシスタントが実行できる操作が決まります。

複数のインスタンス

1つのサーバーから複数の Tickiti インストール環境（本番環境とステージング環境など）に接続するには、 TICKITI_INSTANCES を追加します。値には JSON、または JSON ファイルのパスを指定し、名前を { "base", "token" } に対応付けます。 TICKITI_API_BASE / TICKITI_API_TOKEN の組み合わせはデフォルトのインスタンスとしてそのまま使用され、 TICKITI_INSTANCE_NAME の名前が割り当てられます（デフォルトは default）。

TICKITI_INSTANCE_NAME=production
TICKITI_INSTANCES='{"staging": {"base": "https://staging.example.com", "token": "…"}}'

各ツールでは、任意の instance 引数を指定できます。list_instances で名前を確認できます。

Claude Code での使用

claude mcp add tickiti \
  --env TICKITI_API_BASE=https://support.example.com \
  --env TICKITI_API_TOKEN=YOUR_TICKITI_API_TOKEN \
  -- node /absolute/path/to/tickiti-mcp/dist/server.js

claude mcp list（またはセッション内で /mcp）を実行して確認します。削除するには claude mcp remove tickiti を実行します。

ほかの MCP クライアントでは、それぞれの設定ファイルでサーバーを設定しますが、形式は同じです。 環境変数 TICKITI_API_BASE と TICKITI_API_TOKEN を設定し、 node /absolute/path/to/tickiti-mcp/dist/server.js を stdio サーバーとして実行します。

権限とセキュリティ

サーバーが独自の権限を追加することはありません。すべての呼び出しは、トークンに紐づくスタッフユーザーとして実行され、トークンの権限によって制限されます。直接 API を呼び出す場合と同じです。アシスタントにできることを制限するには、範囲を絞ったトークンを発行します。

• 読み取り専用トークン（例：tickets:read、reports:read）を使うと、アシスタントは内容を確認できても変更はできません。
• 書き込み権限を付与するのは、アシスタントが操作する必要のある分類だけにしてください。
• 呼び出しが拒否された場合、サーバーは理由（権限、ロール、プランの不足）を報告します。

チケットを書き込むツールは、すべての呼び出しで冪等性キーを送信するため、リクエストを再試行してもチケットや返信が重複して作成されることはありません。

長い本文は、content の代わりに content_path（ローカルファイル）で指定できます。ファイルと画像は常にパスで渡します。サーバーが読み込むため、バイト列がモデルを通過することはありません。

仕組み

ファイル	役割
src/client.ts	リクエストの中核：ベース URL、ベアラー認証、冪等性、エラーの正規化
src/result.ts	API の結果を MCP ツール結果のエンベロープにマッピング
src/manifest.ts	生成されたルートマニフェストのヘルパー（検索、パス構築）
src/generated/manifest.ts	自動生成されたルートテーブル（編集しないでください）
src/tools/tickets.ts	チケットの書き込み — 検証済みの入力スキーマ
src/tools/ticket-reads.ts	チケット、返信、添付ファイルの読み取り
src/tools/ticket-operations.ts	削除、統合、リンク、移動、起票者、添付ファイルの削除、検索
src/tools/settings-writes.ts	定型返信とテンプレート
src/tools/admin.ts	メール、テンプレートのレンダリングと画像、パースペクティブ、API キー、インスタンス
src/tools/reads.ts	名前付き読み取りツール（設定／ワークフロー／レポート）
src/tools/generic.ts	list_endpoints + tickiti_call
src/param-hints.ts	専用ツールのないエンドポイントについて、list_endpoints が表示する本文パラメーター
src/server.ts	エントリーポイント：ツールを登録し、stdio トランスポートに接続
scripts/build-manifest.mjs	Tickiti のルートテーブルからマニフェストを再生成

メンテナー

src/generated/manifest.ts は Tickiti 自身のルートテーブル（php artisan route:list --json）から生成されるため、権限、ロール、プランの制限、パスパラメーターを手作業で管理する必要はありません。API の変更後、Tickiti のチェックアウトを使って再生成してください。

TICKITI_DIR=/path/to/tickiti npm run manifest

すべてのエンドポイントを対象とするエンドツーエンドテストが tests/all-paths.mjs にあります（npm run test:paths。スクラッチインスタンスに対するベース URL と全権限トークンが必要です）。また、ツール登録をオフラインで確認するテストが tests/smoke-tools.mjs にあります（npm run build && node tests/smoke-tools.mjs）。

一部のツールは、2026 年 10 月に Tickiti に追加されたエンドポイントを呼び出します。古いインストール環境では 404 が返されます。list_endpoints には最新の API が記載されています。

ライセンス

MIT © Oxenic