IT Glue

mcp-itglue

IT Glue API 用の MCP（Model Context Protocol）サーバーです。ドキュメントを AI アシスタントに読み取らせ、安全に書き込ませたい MSP 向けに構築されています。

• ドキュメントとセクション — 一覧表示、読み取り、作成、更新、公開、削除
• 柔軟なアセット — アセットの種類とフィールドの参照、アセットの一覧表示、読み取り、作成、更新、削除
• ドキュメント内の画像 — base64、URL、ローカルパスからドキュメント内（Text/Step セクション内にインライン、または Gallery 内）に画像をアップロードし、返された <img src> で埋め込みます。ドキュメント画像の取得と削除もできます
• 添付ファイル — レコードの Attachments パネル（ドキュメント、柔軟なアセット、構成など）に任意のファイルを添付します。添付ファイルの一覧表示と削除もできます
• セマンティックベクトル検索 — 「バックアップエージェントを削除する方法」と検索すると、単語が一致しなくても Veeam の廃止手順書が見つかります（OpenAI または Azure OpenAI の埋め込み、ローカル JSON インデックス）
• ロールベースのアクセス制御 — viewer／editor／admin のベアラートークンにより、各セッションに表示されるツールを制御します
• 独自のキーを使用 — クライアントはセッションごとに独自の IT Glue API キーを指定できるため、IT Glue 自身の権限が適用されます
• インデックスの鮮度 — IT Glue の webhook、書き込み後の自動更新、手動更新エンドポイントに対応します
• トランスポート — ローカル利用向けの stdio、共有デプロイメント向けの streamable HTTP に対応し、Docker イメージも含まれています

インストール

IT Glue API キーが必要です（IT Glue → Account → Settings → API Keys）。米国以外のアカウントでは、ITGLUE_REGION を eu または au に設定してください。

npx（推奨）

Claude Desktop（claude_desktop_config.json）または Claude Code（.mcp.json）：

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["-y", "mcp-itglue"],
      "env": { "ITGLUE_API_KEY": "ITG.xxxx" }
    }
  }
}

Claude Code のワンライナー：

claude mcp add itglue --env ITGLUE_API_KEY=ITG.xxxx -- npx -y mcp-itglue

Claude Desktop のユーザーは、最新リリースから mcp-itglue.mcpb をダウンロードすることもできます。Claude Desktop で開き、プロンプトが表示されたら API キーを入力してください。

stdio は常にすべてのツールを利用できる状態で実行されます。独自のキーを使用する、ローカルの単一ユーザー向けトランスポートです。

Docker

コンテナーイメージは、HTTP トランスポート（共有デプロイメント向け）をデフォルトで使用します。

docker run --rm -p 3000:3000 \
  -e ITGLUE_API_KEY=ITG.xxxx \
  ghcr.io/mspstack/mcp-itglue

Docker でローカルの stdio を使用する場合：

{
  "mcpServers": {
    "itglue": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ITGLUE_API_KEY", "ghcr.io/mspstack/mcp-itglue", "--transport", "stdio"],
      "env": { "ITGLUE_API_KEY": "ITG.xxxx" }
    }
  }
}

ソースから

git clone https://github.com/mspstack/mcp-itglue.git && cd mcp-itglue
npm install && npm run build
ITGLUE_API_KEY=ITG.xxxx node dist/index.js

HTTP デプロイメント

ITGLUE_API_KEY=ITG.xxxx \
MCP_TOKENS_VIEWER="alice:$(openssl rand -hex 32)" \
MCP_TOKENS_EDITOR="automation:$(openssl rand -hex 32)" \
MCP_TOKENS_ADMIN="ops:$(openssl rand -hex 32)" \
npx -y mcp-itglue --transport http --port 3000

または Docker を使用する場合：

docker run --rm -p 3000:3000 \
  -e ITGLUE_API_KEY -e MCP_TOKENS_VIEWER -e MCP_TOKENS_EDITOR -e MCP_TOKENS_ADMIN \
  ghcr.io/mspstack/mcp-itglue

エンドポイント：

ルート	目的
POST/GET/DELETE /mcp	MCP streamable-http エンドポイント
GET /health	稼働状態プローブ
POST /webhook/itglue	IT Glue webhook → インデックスの差分更新
POST /index/refresh	手動インデックス更新（共有シークレットまたは admin トークン）
PUT /upload/:id	ステージングファイルのアップロード先（メモリーバックエンド、/mcp と同じ認証）

セッションはメモリー上に保持されます。ロードバランサーの背後では、単一インスタンスを実行するか、スティッキーセッションを追加してください。

アクセス制御

ロールトークン

3 つの環境変数に、カンマ区切りの label:token リストを設定します。

MCP_TOKENS_VIEWER="alice:tokA,bob:tokB"   # read-only tools
MCP_TOKENS_EDITOR="hatz:tokC"             # + create/update/publish, delete section
MCP_TOKENS_ADMIN="ops:tokD"               # + delete documents / flexible assets

クライアントは Authorization: Bearer <token> で認証します。ラベルは監査ログ（[rbac] session … for alice (viewer)）に表示され、全員のトークンをローテーションせずに、特定のユーザーのトークンを無効化できます。

ロールで使用できないツールは、そのセッションには登録されません。viewer には tools/list に itglue_create_document すら表示されません。また、多層防御として、実行時ガードが呼び出しのたびにロールを再確認します。セッション ID に権限が付与されることはありません。すべてのリクエストで再認証が行われ、既存のセッションに異なるプリンシパルを提示すると 403 が返されます。

トークンが設定されていない場合、サーバーは開発モードで実行され、すべてのリクエストに admin アクセスを許可して、起動時に強い警告を表示します。本番環境では使用しないでください。

IT Glue キーの持ち込み（BYOK）

クライアントは、initialize リクエストの x-itglue-api-key ヘッダーで独自の IT Glue API キーを送信できます。その後、セッションはそのキーを使って IT Glue と通信し、すべてのツールを利用できます。実際のアクセス制御には、IT Glue 側のキー権限が適用されます。ポリシーは CLIENT_ITGLUE_KEYS で制御します。

値	動作
with-token（デフォルト）	BYOK を許可しますが、有効なベアラートークンも引き続き必要です。サーバーがオープンプロキシになるのを防ぎます
open	IT Glue キーだけで認証します（信頼できるネットワーク／ローカルでの使用向け）
disabled	ヘッダーを拒否し、サーバー全体で使うキーのみを使用します

BYOK を有効にすると、サーバー全体で使う ITGLUE_API_KEY は任意になります。クライアントキーを指定しないセッションは、明確なエラーとともに拒否されます。クライアントキーがログに記録されることはありません。セッションはキーの SHA-256 ハッシュに紐付けられ、監査ログでは byok:<hash-prefix> としてラベル付けされます。

ツール

ツール	ティア
itglue_list_organizations, itglue_get_organization	読み取り
itglue_list_documents, itglue_get_document	読み取り
itglue_list_document_folders	読み取り
itglue_list_document_sections, itglue_get_document_section	読み取り
itglue_list_flexible_asset_types, itglue_get_flexible_asset_type	読み取り
itglue_list_flexible_assets, itglue_get_flexible_asset	読み取り
itglue_get_document_image	読み取り
itglue_list_attachments	読み取り
itglue_vector_search, itglue_vector_index_status	読み取り
itglue_create_document, itglue_update_document, itglue_publish_document	書き込み
itglue_create_document_section, itglue_update_document_section	書き込み
itglue_delete_document_section †	書き込み
itglue_create_document_image	書き込み
itglue_delete_document_image †	書き込み
itglue_request_upload（HTTP、UPLOAD_STAGING ≠ off の場合）	書き込み
itglue_create_flexible_asset, itglue_update_flexible_asset	書き込み
itglue_create_attachment	書き込み
itglue_build_vector_index	書き込み
itglue_delete_documents	破壊的操作
itglue_delete_flexible_asset	破壊的操作
itglue_delete_attachment	破壊的操作
itglue_find_endpoint, itglue_get ‡	読み取り

Viewer = 読み取り。Editor = 読み取り + 書き込み。Admin = すべて。 † 完全に削除されますが、エディターのティアに属します。エディターはドキュメントの構成変更にこれらを必要とし、更新を使ってセクションの内容を空にしたり、<img> を削除したりすることもできます。

ドキュメント内の画像と添付ファイル

IT Glue には、互いに無関係な 2 つのアップロード方法があります。添付ファイル（itglue_create_attachment）はレコードの「Attachments」サイドパネルに追加され、ドキュメント本文には表示されません。ドキュメントの内部に画像を表示するには、itglue_create_document_image を使います。

1. document_id（インライン画像の場合）、または document_id と gallery_id（Gallery/Step セクションの document_gallery_id）を指定してアップロードします。
2. インライン画像の場合は、返された inline_resource_url をそのままセクションの HTML に入れます。<img src="/6255696/docs/17772862/images/27211966"> — または append_to_section_id を渡すと、ツールが既存の Text/Step セクションに追加します。

IT Glue はセクションの内容から data: URI と自身の S3 URL を削除します。保持されるのは、これらの相対パスと公開 https:// リンクのみです。

クライアントからサーバーにファイルを送る（ステージングアップロード）

ツールの引数はモデルを経由するため、content_base64 が使えるのはごく小さなファイルに限られます。スクリーンショットを送る場合、数メガバイト分の Base64 をモデルがトークンごとに再現する必要があり（切り詰められた結果は IT Glue に NotIdentifiedByImageMagickError で拒否されます）、HTTP 経由ではサーバーがステージングアップロードを提供します。

1. モデルが itglue_request_upload（file_name は任意）を呼び出し、upload_id、URL、すぐに実行できる curl コマンドを受け取ります。
2. クライアントはシェルからその URL にファイルを PUT します。
3. モデルが upload_id を指定して itglue_create_document_image または itglue_create_attachment を呼び出します。

スロットの有効期間は 15 分で、リクエスト元のプリンシパル（トークンのラベル／BYOK キー）に紐づき、一度だけ使用できます。UPLOAD_STAGING で選択するバックエンドは 2 種類です。

モード	PUT の送信先	使用する状況
memory（HTTP でのデフォルト）	このサーバーの PUT /upload/:id。/mcp と同じ Authorization／x-itglue-api-key ヘッダーを使用します。URL にアクセスできるよう PUBLIC_BASE_URL を設定してください。	クライアントからサーバーに直接アクセスできる場合。
azure-blob	Azure Blob Storage 上の短期間有効な SAS URL。サーバーが後から独自の認証情報で BLOB をダウンロードし、削除します。	サーバーがゲートウェイの背後にある場合や、その他の理由でクライアントからアクセスできない場合。AZURE_STORAGE_CONNECTION_STRING（アカウントキー SAS）、または AZURE_STORAGE_ACCOUNT（マネージド ID／DefaultAzureCredential 経由の az login。Storage Blob Data Contributor と Storage Blob Delegator が必要）を設定してください。必要に応じて AZURE_STORAGE_CONTAINER も設定できます（デフォルトは mcp-itglue-uploads）。
off	—	stdio（デフォルト。file_path でローカルディスクから直接読み込みます）、またはこの機能を使用しない場合。

すでにウェブ上でホストされているファイルには、引き続き url が最も簡単な指定方法です。 ‡ 高度なツールセット（オプトイン、デフォルトでは無効）：itglue_get は、キュレーションされたツールでラップされていない任意の API パスに対する読み取り専用 GET パススルーです。また、itglue_find_endpoint はキュレーションされたエンドポイントカタログを検索します。ITGLUE_ADVANCED_TOOLSET=true または --advanced で有効にできます。パスワードのリソース（/passwords）は厳格にブロックされるため、認証情報の値がモデルに渡ることはありません。

ベクターツールは、埋め込みプロバイダーが設定されている場合にのみ表示されます。

ベクトル検索

OPENAI_API_KEY（または AZURE_OPENAI_API_KEY と AZURE_OPENAI_ENDPOINT。この場合、EMBEDDING_MODEL はデプロイ名です）を設定し、組織ごとに itglue_build_vector_index を実行します。インデックスは VECTOR_INDEX_PATH（デフォルトは ./vector-index.json）に保存される JSON ファイルです。一時的なホストでは、永続ボリューム上のパスを指定してください。

インデックスは、次の 3 つの方法で最新の状態に保たれます。

1. IT Glue ウェブフック — IT Glue では、ウェブフックはワークフロー（Admin → Workflows）から送信します。Document トリガー（作成／更新）と Webhook アクションを追加してください。ワークフローアクションではカスタムヘッダーを送信できないため、共有シークレットを URL に含めます。

   https://<host>/webhook/itglue?secret=<ITGLUE_WEBHOOK_SECRET>
   

   次のような JSON ペイロードテンプレートを使用します。

   キー	値
   event	[trigger_name]
   resource_url	[resource_url]
   resource_name	[resource_name]
   organization_name	[organization_name]

   ドキュメント ID は resource_url から解析されます。トリガー名のキーワードに基づいて、作成／更新／削除が判別されます。x-itglue-webhook-signature HMAC-SHA256 ヘッダーを含む、従来の JSON:API スタイルのペイロードにも対応しています。

2. 自動更新 — このサーバーのツール経由で作成／更新／公開／削除されたドキュメントは、バックグラウンドで自動的に再インデックス化されます。

3. 手動更新 — Authorization: Bearer <ITGLUE_WEBHOOK_SECRET>（または x-refresh-secret ヘッダー、または管理者トークン）を指定して POST /index/refresh を呼び出します。本文に {"document_id": "123"} を指定すると 1 件のドキュメントを更新し、本文が空の場合はインデックス化されたすべての組織を再クロールします。202 を返し、バックグラウンドで処理します。

設定リファレンス

変数	デフォルト	用途
ITGLUE_API_KEY	—	サーバー全体で使用する IT Glue API キー
ITGLUE_REGION	us	us、eu、または au
ITGLUE_BASE_URL	リージョンごと	API のベース URL を上書きします
TRANSPORT	stdio	stdio または http
PORT	3000	HTTP ポート
MCP_TOKENS_VIEWER/EDITOR/ADMIN	—	ロールごとの label:token,label:token
CLIENT_ITGLUE_KEYS	with-token	BYOK ポリシー：disabled、with-token、open
ALLOWED_ORIGINS	—	/mcp で許可する追加のブラウザーオリジン（カンマ区切り）。Origin ヘッダーのないリクエストと localhost オリジンは常に許可されます。それ以外のブラウザーオリジンは 403 で拒否されます
ITGLUE_ADVANCED_TOOLSET	false	true/1 にすると、高度なツールセット（itglue_get、itglue_find_endpoint）を登録します
ITGLUE_WEBHOOK_SECRET	—	Webhook 署名および /index/refresh 用のシークレット
VECTOR_INDEX_PATH	./vector-index.json	ベクトルインデックスファイル
OPENAI_API_KEY	—	ベクトル検索（OpenAI）を有効にします
AZURE_OPENAI_API_KEY / AZURE_OPENAI_ENDPOINT / AZURE_OPENAI_API_VERSION	—	ベクトル検索（Azure OpenAI）を有効にします
EMBEDDING_MODEL	text-embedding-3-small	埋め込みモデル／Azure デプロイ

CLI フラグ --transport、--port、--region、--base-url、--advanced は環境変数より優先されます。詳細は mcp-itglue --help を実行してください。

注意事項と制限

• IT Glue のレート制限は、キーごとに 5 分間で 3000 リクエストです。
• IT Glue のドキュメント API は一部しか文書化されていません。ドキュメント／セクションのエンドポイントは、確認されている API の動作に従います。
• Flexible Asset の特性を更新すると、特性オブジェクト全体が置き換えられます。更新ツールの説明では、モデルにすべての特性を返すよう警告しています。
• リストツールは、クライアントのトークン上限内にデフォルトのページサイズを収めるため、各項目の要約フィールドを（テキストと structuredContent の両方で）返します。itglue_get_* ツールは完全なレコードを返します。
• IT Glue にはユーザーの偽装機能がありません。API キーは常にそれ自体として動作します。ここでの RBAC は、セッションが実行できるツール呼び出しを制御します。BYOK は IT Glue 独自のキー権限に委ねられます。

開発

npm install
npm run dev          # stdio via tsx
npm run dev:http     # http via tsx
npm test             # vitest
npm run build        # tsc → dist/

作者

Eugene Samotija（@selic）によって作成 — defency.net。 その他のプロジェクト：github.com/selic · LinkedIn

ライセンス

MIT