IT Glue

IT Glue MCP サーバー

Claude が IT Glue のドキュメントとアセット管理にアクセスできるようにする、Model Context Protocol（MCP）サーバーです。

ワンクリックデプロイ

メモ

他の Wyre MCP サーバーとは異なり、このサーバーは IT Glue API と直接通信し、 非公開の @wyre-ai/* ランタイム依存関係がないため、ワンクリックビルドに GitHub Packages のトークンは不要です。クラウドビルダーの npm ci が取得するのは パブリックパッケージのみです。（公開済みの @wyre-ai/itglue-mcp パッケージ自体を インストールする場合のみ、read:packages トークンが必要です。インストールを参照してください。） DigitalOcean のターゲットは完全な Docker イメージをビルドし、MCP サーバー全体を HTTP 経由で実行するため、推奨される方法です。このリポジトリには Workers の エントリーポイント（src/worker.ts）が含まれていないため、DigitalOcean または 事前ビルド済みのコンテナーイメージ（ghcr.io/wyre-ai/itglue-mcp）を推奨します。

インストール

このパッケージは GitHub Packages の npm レジストリで公開されており、パブリックパッケージでもトークンが必要です。npm の認証を一度行ってからインストールしてください。

# Authenticate npm to GitHub Packages (token needs the read:packages scope)
export NODE_AUTH_TOKEN=$(gh auth token)   # or a PAT with read:packages

npm install @wyre-ai/itglue-mcp

このリポジトリの .npmrc はすでに @wyre-ai スコープを GitHub Packages に設定し、NODE_AUTH_TOKEN からトークンを読み込むため、追加の設定は不要です。npx @wyre-ai/itglue-mcp にも同じことが当てはまります。

または、Docker イメージを使用してください。

docker pull ghcr.io/wyre-ai/itglue-mcp:latest

設定

.env.example をコピーし、以下の変数を設定してください。このファイルでは CONDUIT_S2S_SECRET を空のままにしてください。実際の値は絶対にコミットしないでください。

変数	説明	必須
ITGLUE_API_KEY	IT Glue API キー（形式：ITG.xxx）。stdio と、AUTH_MODE=env の場合の HTTP で使用します。	はい（stdio および env モード）
ITGLUE_JWT	API キーで Document Folders リソースにまだアクセスできないテナントで、ドキュメントフォルダー操作に対する任意のフォールバックとして使用するユーザーセッション JWT です。ドキュメントフォルダー操作の JWT フォールバックをご覧ください。	いいえ
ITGLUE_REGION	API リージョン：us、eu、または au（デフォルト：us）	いいえ
ITGLUE_BASE_URL	IT Glue API のベース URL を上書きします（上級者向け）	いいえ
MCP_TRANSPORT	トランスポート：stdio（ローカル）または http（リモート）。npx／node 経由で実行する場合は stdio、Docker イメージでは http がデフォルトです。	いいえ
MCP_HTTP_PORT	HTTP トランスポートのポート（デフォルト：8080）	いいえ
MCP_HTTP_HOST	実際の CONDUIT_S2S_SECRET が設定されている場合のバインドアドレスです。未設定の場合は、従来のコンテナバインドである 0.0.0.0 が維持されます。イメージと Compose は、コンテナ内で 0.0.0.0 を設定します。	いいえ
AUTH_MODE	env（環境変数から認証情報を読み込みます。イメージのデフォルト）または gateway（HTTP ヘッダーからリクエストごとに認証情報を読み込みます。Compose のデフォルト）。ゲートウェイモードでは ITGLUE_* にフォールバックしません。	いいえ
CONDUIT_S2S_SECRET	HTTP 用のサービス間シークレットです。空の場合、または既知のプレースホルダー（changeme、secret、replace-me、your-s2s-secret、その他のサンプル値）の場合、プロセスはエラーをログに記録してゼロ以外の終了コードで終了します。openssl rand -hex 32 で生成してください。Compose はこの値がないと起動しません。この値がログに記録されることはありません。	HTTP では必須
MCP_ALLOW_INSECURE_DEV	CONDUIT_S2S_SECRET なしで HTTP を起動する場合は、ローカル開発に限り 1 を設定してください。プロセスは警告をログに記録し、X-Gateway-S2S の検証を行わず、127.0.0.1 のみをバインドします。ループバック以外の MCP_HTTP_HOST を指定すると、起動を拒否します。既知のプレースホルダーシークレットが指定されている場合も、起動を拒否します。	いいえ

/health と /healthz は認証されず、認証情報も読み込みません。stdio トランスポートでは CONDUIT_S2S_SECRET を使用しません。

AUTH_MODE=gateway の場合、MCP Gateway は環境変数ではなく HTTP ヘッダーを介して、リクエストごとに認証情報を注入します。HTTP 認証およびリモートデプロイをご覧ください。

HTTP 認証

MCP_TRANSPORT=http で CONDUIT_S2S_SECRET が設定されている場合、すべての /mcp リクエストに X-Gateway-S2S が含まれている必要があります。検証処理は src/s2s-verify.ts の verifyS2sHeader です。ヘッダー値は t=<unix seconds>,v1=<hex> で、hex は CONDUIT_S2S_SECRET をキーとして、文字列 t=<unix seconds> そのものを HMAC-SHA256 でハッシュした値（小文字の 16 進数 64 文字）です。タイムスタンプはサーバーの時計から 300 秒以内でなければなりません。ヘッダーがない場合、または無効な場合は、ベンダー認証情報が読み込まれる前に HTTP 401 が返されます。

TS=$(date +%s)
SIG=$(printf 't=%s' "$TS" | openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" -hex | awk '{print $NF}')
curl -sS http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H "X-Gateway-S2S: t=${TS},v1=${SIG}" \
  -H "X-ITGlue-API-Key: $ITGLUE_API_KEY" \
  -H "X-ITGlue-Region: us" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

AUTH_MODE=gateway の場合、/mcp には X-ITGlue-API-Key（または X-API-Key）か X-ITGlue-JWT も必要です。これらのヘッダーのみが、そのリクエストに対する認証情報の取得元になります。AUTH_MODE=env でも署名付きの X-Gateway-S2S ヘッダーが必要で、その後、環境変数から ITGLUE_API_KEY と ITGLUE_JWT を使用します。

ドキュメントフォルダー操作での JWT フォールバック

JWT は任意です。必要になるのは、テナントの API キーでドキュメントフォルダーにまだアクセスできない場合だけです。フォルダー関連の各処理では、まず API キーを試します。

• search_documents — デフォルトでは、フォルダーを含む一覧を返します（filter[document_folder_id]=null は、フォルダーに属するものも含めてすべてのドキュメントを返し、各結果には documentFolderId が含まれます）。テナントの API がこのフィルターを拒否した場合、サーバーは [ne] 形式のフィルターを再試行し、最後に従来のルート階層のみの一覧に切り替え、その旨を結果に記載します。どのレイヤーでも JWT は使用されません。
• list_document_folders — IT Glue の公開 API（API キー）では、現在ドキュメントフォルダーのリソースが公開されており、2026 年を通じて各テナントに順次展開されています。サーバーはまず API キーを試し（組織との関連付けパス、次にトップレベルの /document_folders パス）、キーが拒否された場合にのみ JWT にフォールバックします。
• create_document — 名前でフォルダーを選択する際は、同じくまず API キーで一覧取得を試し、次に設定済みの JWT を使用します。どちらでもフォルダーを一覧取得できない場合は、最後の手段としてフォルダー URL、同階層のドキュメント URL、または数値のフォルダー ID を求めます。

JWT フォールバックが必要な場合は、デプロイ方法に応じて次のいずれかの方法で指定してください。

モード	JWT の指定方法
ローカル／環境変数（AUTH_MODE=env）	ITGLUE_JWT 環境変数を設定します。
リモートゲートウェイ（AUTH_MODE=gateway）	X-ITGlue-JWT リクエストヘッダーを送信します。
対話型クライアント（Claude Desktop/Code）	設定しないでください。初回使用時にサーバーから JWT の貼り付けを求められ、セッション中はキャッシュされます。

ヘッドレス環境へのデプロイ（Docker、クラウド）： 対話型プロンプトに応答する人がいないため、テナントの API キーでフォルダーを一覧取得できない場合は、フォルダーを一覧取得できるように ITGLUE_JWT（env モード）を設定するか、X-ITGlue-JWT（gateway モード）を送信する必要があります。

ブラウザーから JWT を取得する方法：

1. ブラウザーで IT Glue にサインインします。
2. DevTools を開き、Network タブを選択します。
3. itg-api-*.itglue.com へのリクエストをクリックします。
4. リクエストヘッダー Authorization: Bearer <token> の値をコピーします。<token> の部分が JWT です。

有効期限： IT Glue の JWT は有効期間が短く（約 2 時間）、長時間稼働するコンテナーの ITGLUE_JWT に設定した JWT は期限切れになり、更新されるまで JWT フォールバックが失敗します。対話型クライアントでは、有効期限が切れると再度入力を求められます。API キーを使用する操作には影響しません。

利用可能なツール

組織

• search_organizations - 名前、種類、ステータス、PSA ID による任意のフィルタリングを使って組織を検索します
• get_organization - ID を指定して特定の組織を取得します

構成（デバイス／資産）

• search_configurations - 組織、名前、種類、ステータス、シリアル番号、RMM ID、PSA ID で絞り込んで構成を検索します
• get_configuration - ID を指定して特定の構成を取得します
• archive_configuration - 構成をアーカイブします（ソフト削除。通常のビューには表示されなくなりますが、復元可能です）。unarchive_configuration で元に戻せます。PSA／RMM 統合から同期された構成（psaIntegration: enabled／syncActive: true）は、次回の同期で復元または更新される可能性があるため、先にソースシステム（Autotask／Datto RMM）を整理してください
• unarchive_configuration - アーカイブ済みの構成を復元し、再び通常のビューに表示します

ロケーション（住所／サイト）

• search_locations - 組織のロケーション（組み込みの住所／サイトレコード）を検索し、組織、名前、市区町村、地域、国で絞り込みます。結果には住所フィールドと電話番号が含まれます。
• get_location - ID を指定して特定のロケーションを取得します。完全な住所と電話番号も含まれます
• create_location - 組織の新しいロケーションを作成します（name、通常は country_id が必要です）
• update_location - 既存のロケーションを更新します。指定したフィールドのみが変更されます

パスワード

• search_passwords - パスワードエントリを検索します（メタデータのみ。結果に実際のパスワードは含まれません）
• get_password - 実際のパスワード値を含む、特定のパスワードエントリを取得します

ドキュメント

• search_documents - 組織、名前、またはフォルダーで絞り込んでドキュメントを検索します。デフォルトではフォルダーを含む一覧を返します（各結果には documentFolderId が含まれます）。フォルダーフィルターを拒否する API を使用しているテナントでは、ルートのみの一覧に適切にフォールバックします
• get_document - セクション分けされた本文を含む、ID で指定したドキュメントを取得します。MCP Apps ホストではインタラクティブカードとして表示されます。インタラクティブドキュメントカードを参照してください
• list_document_folders - 組織のドキュメントフォルダー（名前と ID）を一覧表示します。IT Glue が Document Folders リソースを公開しているテナントでは API キーで動作します。それ以外の場合は JWT にフォールバックします。ドキュメントフォルダー操作の JWT フォールバックを参照してください
• create_document - 必要に応じて本文を指定して、組織内にドキュメントを作成します。フォルダーが指定されていない場合はフォルダーを尋ねます。組織のルートに作成するには skip_folder_prompt=true を渡します
• update_document - ドキュメントの名前を変更します。変更されるのは指定した名前のみです。フォルダーの移動には対応していません。IT Glue の Documents API では、PUT/PATCH で document_folder_id を指定できないとされています
• list_document_sections - 編集前に、ドキュメントのセクションを順番に一覧表示します
• create_document_section - 見出しまたはテキストのセクションを追加します。編集後に publish_document を呼び出してください
• update_document_section - セクションの内容を置き換えます。編集後に publish_document を呼び出してください
• delete_document_section - ⚠ セクションを完全に削除します（取り消せません）。編集後に publish_document を呼び出してください
• publish_document - セクションの変更を公開し、表示されるようにします
• archive_document - ドキュメントをソフト削除します（通常のビューでは非表示になりますが、unarchive_document で復元できます）
• unarchive_document - 以前にアーカイブしたドキュメントを復元します
• delete_document - ⚠ ドキュメントとすべてのセクションを完全に削除します（取り消せません。再び必要になる可能性がある場合は archive_document を優先してください）

添付ファイル

• create_attachment - チェックリスト、チェックリストテンプレート、構成、連絡先、ドキュメント、ドメイン、フレキシブルアセット、場所、パスワード、SSL 証明書、またはチケットにファイルを添付します。Base64 で入力します。ドキュメント本文に画像を追加する唯一の対応方法でもあります。ドキュメント内の画像を参照してください
• list_attachments - レコードの添付ファイルをダウンロード URL とともに一覧表示します

フレキシブルアセット

• search_flexible_assets - フレキシブルアセットを検索します（flexible_asset_type_id が必要です）

ユーザーメトリクス

• search_user_metrics - ユーザーのアクティビティ指標を検索します。ユーザー別、組織別、リソースタイプ別に、日付ごとに集計された created／viewed／edited／deleted アクションの件数を取得します。user_id、organization_id、resource_type、start_date／end_date の範囲で絞り込み、id、created、viewed、edited、deleted、date で並べ替えます（降順にするには先頭に - を付けます）。

  これは IT Glue のユーザー評価スコアの基になる生データです。そのため、「実際にドキュメントを保守しているのは誰か」を、技術者別、クライアント別、リソースタイプ別に確認できます。

  日付範囲のルール（2026-08-06 に api.itglue.com に対して実環境で検証済み）：

  • 範囲は開始日から終了日まで最大 7 日間です。そのため、2026-08-01,2026-08-08 は受け付けられます（暦日で数えると8日間）が、2026-08-01,2026-08-09 は422を返します。APIが比較するのは日付の差であり、両端を含めた日数ではありません。「1週間より長い」を両端を含む7日間と解釈すると、有効なクエリを誤って拒否することになります。
  • end_date には start_date が必要です。 IT Glue はワイルドカードで始まるフィルター（*,2026-08-07 → 422）を拒否するため、終了日のみを指定すると、絞り込み範囲が狭まるのではなく、確実にエラーになります。終了日を開いた範囲にする（2026-08-01,*）のは問題ありません。
  • どちらの違反も同じ422タイトル（"date range filter cannot be longer than a week, and cannot start with a wildcard"）を返すため、APIからどちらに該当したかは分かりません。このツールは両方を事前にチェックし、API呼び出しを行わずに該当するルールを伝えます。
  • 日付を両方とも省略すると、IT Glue 独自のデフォルト期間が適用されます。

  注意点 — 不明なフィルターキーは黙って無視されます。 filter[not-a-real-key]=x はエラーではなく、フィルターされていない結果全体を含む HTTP 200 を返します（実環境で検証済み）。そのため、フィルター名の入力ミスや記憶違いがあっても、正しく絞り込まれたクエリのように見えながら、実際にはすべてのデータが返されます。結果の範囲が広すぎるように見える場合は、意図的に存在しない値（filter[resource-type]=ZZZNoSuchType は正しく0件を返します）を使って、行数を照合してください。

ユーティリティ

• itglue_health_check - IT Glue API への接続を確認します

インタラクティブなドキュメントカード（MCP Apps）

get_document は MCP Apps ホスト（Claude Desktop/web）でインタラクティブなカードとして表示され、ドキュメント名、組織、フォルダー、主な日付、各セクションのプレーンテキストプレビューが表示されます。他のホストでのプレーンなJSONの動作に変更はありません。カードは読み取り専用で、デフォルトではニュートラルなデザインです。window.__BRAND__ の注入または MCP_BRAND_* 環境変数（MCP_BRAND_NAME、 MCP_BRAND_LOGO_URL、MCP_BRAND_PRIMARY_COLOR、MCP_BRAND_ACCENT_COLOR、 MCP_BRAND_BG、MCP_BRAND_TEXT）でブランド設定が可能で、再ビルドは不要です。

ドキュメント内の画像

ドキュメント本文に画像を挿入する場合、画像形式ではなく添付ファイル形式で扱われます。 2026-08-31 に api.itglue.com で実際に検証済みです。

試した内容	結果
セクション HTML 内のインライン <svg>	通知なく削除されます。 セクションは保存され、200 が返されますが、保存されたコンテンツから図が消えています
<img src="data:image/png;base64,…">	検証エラーではなく、500 で拒否されます
POST /documents/{id}/relationships/document_images	404
添付ファイルをアップロードしてから、<img src="https://…/attachments/{id}"> を指定する	動作し、インラインで表示されます

この 404 については、誤解しやすいため注意点があります。ドキュメント画像は実在するリソースです。IT Glue のウェブエディターは画像を作成し、セクション HTML 内に /{org_id}/docs/{doc_id}/images/{image_id} のような 相対 パスを保存します。読み込み時には、レンダラーがこれを署名付き S3 URL に置き換えます。見つからなかったのは、画像を作成するための公開 API として文書化されたルートです。エディターは内部エンドポイントを使用しているようです。したがって、「公開 API の画像アップロードルートが見つからない」と解釈するのが適切であり、「ドキュメント画像は存在しない」という意味ではありません。

そのため、create_attachment を使います。ファイルをアップロードし、返された downloadUrl を参照してください。インライン SVG のケースは、書き込みが成功したように見えるため、知っておく価値があります。

create_attachment(resource_type="documents", resource_id, file_name, content)
→ reference the returned downloadUrl from an <img src> in update_document_section
→ publish_document

サニタイザーはインラインスタイルの一部のプロパティ（max-width など）も削除するため、CSS に頼らず、希望する幅に合わせて画像のサイズを調整してください。

生の base64 を渡してください。data:...;base64, のプレフィックスが付いたままだと、ツールはそれを渡さずに削除します。IT Glue は渡された内容をそのまま保存するため、プレフィックス付きのペイロードはアップロード自体は「成功」しますが、ファイルが破損し、誰かが開いたときに初めて問題が表面化します。

Claude Code での使用方法

.mcp.json に追加します。

{
  "mcpServers": {
    "itglue": {
      "command": "npx",
      "args": ["@wyre-ai/itglue-mcp"],
      "env": {
        "ITGLUE_API_KEY": "${ITGLUE_API_KEY}",
        "ITGLUE_REGION": "us"
      }
    }
  }
}

または、Docker を使用する場合（ローカル stdio）：

{
  "mcpServers": {
    "itglue": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "MCP_TRANSPORT=stdio",
        "-e", "ITGLUE_API_KEY",
        "ghcr.io/wyre-ai/itglue-mcp:latest"
      ],
      "env": {
        "ITGLUE_API_KEY": "${ITGLUE_API_KEY}"
      }
    }
  }
}

注： Docker イメージはデフォルトで HTTP トランスポートを使用します。Claude Desktop/Code 用のローカル stdio サーバーとして実行するには、上記の -e MCP_TRANSPORT=stdio が必要です。サーバーへのデプロイについては、以下のリモートデプロイを参照してください。

リモートデプロイ（HTTP Streamable）

サーバー／クラウドにデプロイする場合は、HTTP Streamable トランスポートを使用してサーバーを実行してください。Docker イメージはデフォルトでポート 8080 の MCP_TRANSPORT=http を使用し、コンテナ内では 0.0.0.0 で待ち受けます。起動時に、CONDUIT_S2S_SECRET が有効なシークレットでなければ実行を拒否します。前段にプロキシがない場合は、ポートをループバックにバインドしてください。エンドポイントは 2 つあります。

• POST /mcp — MCP Streamable HTTP エンドポイント（ステートレス：リクエストごとに新しいサーバーが作成されます）。有効な X-Gateway-S2S ヘッダーが必要です。HTTP 認証を参照してください。
• GET /health および GET /healthz — 認証不要のヘルスチェック。認証情報は読み取りません。

Env モード（単一テナント）

S2S 認証の成功後、認証情報は環境変数から取得されます。1 つの API キーでデプロイ環境を運用する場合に使用してください。イメージのデフォルトは AUTH_MODE=env です。

docker run -d \
  --name itglue-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e ITGLUE_API_KEY="ITG.xxxxxxxx" \
  -e ITGLUE_REGION="us" \
  --restart unless-stopped \
  ghcr.io/wyre-ai/itglue-mcp:latest

# Verify
curl http://127.0.0.1:8080/health
# {"status":"ok","transport":"http","authMode":"env",...}

クライアントは MCP Streamable HTTP トランスポートを使用して http://127.0.0.1:8080/mcp に接続し、X-Gateway-S2S を送信する必要があります。

ゲートウェイモード（マルチテナント／ホステッド）

MCP Gateway（例：mcp.wyre.ai）の背後にデプロイする場合は、AUTH_MODE=gateway を設定してください。認証情報は環境変数ではなく、リクエストごとに HTTP ヘッダー経由で注入されます。両方の認証情報ヘッダーがないリクエストには 401 が返され、プロセス環境内の ITGLUE_API_KEY または ITGLUE_JWT にはフォールバックしません。Compose はこのモードで動作します。これらの変数を設定せず、env_file も使用しないため、プロジェクトの .env からベンダーの静的認証情報が注入されることはありません。ただし、Compose には CONDUIT_S2S_SECRET が必要です。

docker run -d \
  --name itglue-mcp \
  -p 127.0.0.1:8080:8080 \
  -e CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  -e AUTH_MODE=gateway \
  --restart unless-stopped \
  ghcr.io/wyre-ai/itglue-mcp:latest

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" docker compose up

ゲートウェイは各リクエストで認証情報と X-Gateway-S2S 証明を提供します。

ヘッダー	説明	必須
X-Gateway-S2S	CONDUIT_S2S_SECRET で署名された t=<unix seconds>,v1=<hex hmac-sha256>。 HTTP 認証を参照してください。	はい
X-ITGlue-API-Key（または X-API-Key）	IT Glue API キー	API キーまたは JWT のいずれか
X-ITGlue-JWT	スコープ昇格操作用の JWT	API キーまたは JWT のいずれか
X-ITGlue-Region	API リージョン：us、eu、または au（デフォルト：us）	いいえ
X-ITGlue-Base-URL	IT Glue API のベース URL を上書きします	いいえ

X-ITGlue-API-Key と X-ITGlue-JWT の両方がないリクエストには 401 が返されます。このモードでは、/health エンドポイントは "authMode":"gateway" を報告し、これらのヘッダーを読み取りません。

Docker を使用せずに実行する

インストール済み／ビルド済みのコピーでも、MCP_TRANSPORT=http を設定すれば同じトランスポートを使用できます。CONDUIT_S2S_SECRET が設定されるまで起動しません。

CONDUIT_S2S_SECRET="$CONDUIT_S2S_SECRET" \
  MCP_TRANSPORT=http MCP_HTTP_PORT=8080 ITGLUE_API_KEY="ITG.xxxxxxxx" \
  npx @wyre-ai/itglue-mcp

シークレットなしでのローカル HTTP は開発専用です。127.0.0.1 にバインドし、警告をログに記録します。ループバック以外の MCP_HTTP_HOST（0.0.0.0 を含む）を指定すると、起動は終了します。

MCP_TRANSPORT=http MCP_HTTP_HOST=127.0.0.1 MCP_ALLOW_INSECURE_DEV=1 \
  npx @wyre-ai/itglue-mcp

クエリ例

設定が完了したら、Claude に次のように尋ねられます。

• 「IT Glue で『Acme』を含む組織を検索して」
• 「デバイス ID 12345 の構成詳細を取得して」
• 「組織 ID 100 のすべてのパスワードを検索して」
• 「タイプ 54321 のフレキシブルアセットを検索して」

セキュリティに関する注意事項

• セキュリティ上、パスワードの検索結果には実際のパスワード値は含まれません
• パスワード値を取得するには、明示的な ID を指定して get_password を使用してください
• API キーは、環境変数またはシークレットマネージャーを使用して安全に保管してください
• API キーには、IT Glue で適切な読み取り権限が必要です

ライセンス

Apache-2.0

コントリビューション

ガイドラインについては、CONTRIBUTING.mdを参照してください。