qseow-mcp

qseow-mcp

Qlik Sense Enterprise on Windows（クライアント管理型）向けの MCP サーバーです。

Qlik サポートエージェントの連携レイヤーです。 Qlik Cloud にはネイティブの MCP エンドポイントが用意されていますが、クライアント管理型の環境（現在も大規模なエンタープライズ Qlik 環境の多くが稼働している環境）には、それに相当するものがありません。このサーバーは、オンプレミスの API（Repository/QRS、Engine/QIX、Proxy）をModel Context Protocolのツールとして公開するため、エージェントはサポートエンジニアと同じように、数値が正しくないときに KPI → オブジェクト → シート → アプリ → スクリプト → ソースをたどり、各段階で定義を評価できます。さらに、サイトのガバナンス、クエリ、構築も行えます。

ステータス：0.5.2、プレリリースです。 シングルノードのサイト上で、Qlik Sense May 2026（15.13.8） に対して、証明書認証と JWT 認証の両方で全 44 個のツールをエンドツーエンドでテスト済みです（完全な変更ライフサイクル：copy → set_script → reload → publish → delete、およびタスクの開始から完了までを含みます）。ツール名や形式は今後変更される可能性があります。

qseow-mcp は Terenzi LLC による独立したオープンソースプロジェクトです。QlikTech International AB との提携、同社による承認・後援はありません。Qlik®、Qlik Sense® および関連する商標は QlikTech International AB の商標であり、このサーバーが連携するソフトウェアを識別する目的でのみ使用しています。

インストール

Claude Desktop — ワンクリック。 最新リリースから qseow-mcp-<version>.mcpb をダウンロードし、ダブルクリックしてください。Claude Desktop がホスト名と証明書のパスを尋ねます。編集する JSON も、実行する npm install もありません。

あらゆる MCP クライアント — npx 経由。 クローンもビルドも不要です。

{
  "mcpServers": {
    "qseow": {
      "command": "npx",
      "args": ["-y", "qseow-mcp"],
      "env": {
        "QSEOW_HOST": "sense.example.com",
        "QSEOW_CERT_PATH": "/absolute/path/to/client.pem",
        "QSEOW_CERT_KEY_PATH": "/absolute/path/to/client_key.pem",
        "QSEOW_ROOT_CERT_PATH": "/absolute/path/to/root.pem"
      }
    }
  }
}

Claude Code でも同じことを 1 行で実行できます。

claude mcp add qseow --scope user \
  -e QSEOW_HOST=sense.example.com \
  -e QSEOW_CERT_PATH=/absolute/path/to/client.pem \
  -e QSEOW_CERT_KEY_PATH=/absolute/path/to/client_key.pem \
  -- npx -y qseow-mcp

証明書は QMC → Certificates → Export（PEM を選択）から取得できます。証明書の代わりに JWT を使用する場合は、認証を参照してください。

起動時は読み取り専用です。 QSEOW_ALLOW_MUTATIONS=true を設定するまで、変更系ツールは登録されないため、クライアントに表示されるツール一覧は、設定を変更するまで実際に読み取り専用となります。

ペルソナ別のツール

QSEOW_TOOL_GROUPS を使用すると、各デプロイに必要なツールだけを公開できます。

アナリスト — データについて質問する（Engine/QIX）

ツール	目的
list_engine_apps	セッションから参照できるアプリ
get_app_data_model	テーブル、フィールド、行数、カーディナリティ
evaluate_expression	現在の選択状態で Qlik 式を評価
create_hypercube	グループ化クエリ：ディメンション × メジャー → 行
get_field_values	選択状態とともに個別の値を取得。任意で検索も可能
select_field_values / clear_selections / get_current_selections	選択状態を操作・確認
crosscheck_expression	敵対的なセルフチェック：合計値とグループ別合計を比較し、ユーザーに数値を提示する前に、加算できないメジャーやスコープの不具合を検出

値を返すすべての分析ツールには信頼性エンベロープが付属します。式の検証警告（フィールド名の誤字があっても、エンジンの最も厄介な挙動により、エラーにならず null/0 が返されます）と、その値の計算時に有効だった選択状態が含まれるため、フィルター適用後の数値が未フィルター状態の真実を装うことはありません。

インスペクター — トラブルシューティングの手順（アナリストグループに同梱）

ツール	目的
list_sheets / get_sheet_objects	UI レイヤーをたどる：シートとその上のオブジェクト
get_object_properties	任意のオブジェクトの qProps 全体 — 定義レイヤー
search_expressions	すべてのオブジェクト（所有するシートを含む）、マスターアイテム、変数、スクリプトからフィールド、KPI、式の一部を検索
list_master_measures / list_master_dimensions	ガバナンス対象の定義一覧
evaluate_master_measure	ID またはタイトルでマスターメジャーを評価（[Name] がフィールドとして解決される問題を回避）
get_app_lineage	すべての LOAD/STORE ソースとターゲットを分類して表示（qvd、database、inline、resident、store）
公開済みアプリに関する注意事項： エンジンは、ユーザー ID から公開済みアプリの スクリプト と 系譜 を隠します（内部証明書 ID はこの制限を回避します）。サポートエージェントのパターンは、copy_app → 所有するコピーを追跡する、です。コピーには同じスクリプトと定義が引き継がれます。

開発者 — アプリを構築してデプロイします（Engine + QRS）

ツール	用途
create_sheet / add_sheet_object	UI レイヤーを構築します：シートとビジュアライゼーション。作成時にレンダリング検証ゲートが実行され、その判定結果が返されます
validate_sheet	品質ゲート（読み取り専用）：これらのオブジェクトは実際にレンダリングされますか？定義エラー、未知のフィールド／タイプ、空のキューブ、ピボットの qMode に関する落とし穴、nebula プロパティブロックの欠落、セル配置のリント
get_script / set_script	アプリのロードスクリプトを読み取り、置き換えます
check_script	再読み込みせずに構文をチェックします
reload_app	再読み込みして保存し、進捗の末尾を返します
create_app	アプリを作成し、必要に応じてスクリプトを設定して再読み込みします
copy_app / publish_app / delete_app	複製、ストリームへの公開、削除を行います

管理者 — サイトを管理します（QRS）

ツール	用途
qrs_about / service_status	バージョン、各ノード上のすべてのサービスの健全性
license_summary	シリアル番号、エディション、有効期限、professional／analyzer の割り当て
list_apps / list_streams / list_tasks / list_users	インベントリ。すべてフィルター可能です
start_task	リロードタスクを開始します
list_extensions / list_data_connections	拡張機能と接続のインベントリ
qrs_search	任意の QRS エンティティとフィルター式 — ガバナンスの強力なツールです
get_reload_log	リロードが失敗した理由を確認します。最後の実行結果、詳細なタイムライン、スクリプトログの末尾
engine_healthcheck	エンジンのバージョン、飽和状態フラグ、メモリ／CPU、ロード済みアプリ、セッション数
security_rule_audit	デコード済みアクションとリント結果（無効なデフォルト設定、ワイルドカードフィルター、無条件の書き込み許可）を含むすべてのセキュリティルール
list_user_sessions / end_user_sessions	ユーザーごとのアクティブなプロキシセッション。強制ログアウトを行います。証明書認証が必要です — 以下の注記を参照

変更を伴うツール（set_script、reload_app、create_app、copy_app、publish_app、delete_app、start_task、end_user_sessions、create_sheet、add_sheet_object）は、登録時に制限されます。QSEOW_ALLOW_MUTATIONS=true でない限り、これらは登録されないため、読み取り専用のデプロイでは、tools/list に実質的に読み取り専用のツール群が表示されます。デフォルトは読み取り専用です。

すべてのツールには MCP ツールアノテーション（readOnlyHint、destructiveHint、idempotentHint、openWorldHint）が付与されているため、これらを尊重するクライアントは独自のポリシーを適用できます。たとえば、reload_app／set_script／start_task は破壊的操作としてフラグ付けされます。選択ツールは非破壊的なセッション状態の変更です。

認証情報のマスキングは、すべての QRS 外部出力経路に適用されます。list_data_connections と汎用の qrs_search（任意のエンティティタイプ、要約表示または full:true）では、認証情報を含むフィールド（password、passphrase、clientsecret など）と、接続文字列に埋め込まれたシークレット（PWD=...、apikey=...）が再帰的にマスキングされます。空または null の認証情報フィールドはマスキングされずにそのまま渡されます。「認証情報なし」は正当なシグナルです。

すべてのリストツールはページ分割に対応しています（offset／limit、エンベロープ {total, offset, returned, truncated, items}）。そのため、数千件のアプリやユーザーがあるサイトでも、クライアントのコンテキストウィンドウを圧迫しません。

レンダリングの検証

最新の Sense ビジュアライゼーションは、エンジンではなくクライアントがレンダリングする nebula.js のスーパーノバです。エンジンが問題なく受け入れて評価するハイパーキューブでも、スーパーノバのデフォルトのプロパティブロックが欠けていると、レンダリング結果は空白になります（ブラウザーでは Cannot read properties of undefined が発生しますが、エンジンはそのことを認識しません）。ビルダーはタイプごとにこれらのブロックを設定し、validate_sheet は不足しているオブジェクトにフラグを立てます。

エンジン側の検証では実際の描画を確認できないため、2 つのスクリプトで一連の検証を完結させます。scripts/viz_matrix.mjs は稼働中のサイトでサポートされている各タイプのオブジェクトを 1 つずつ作成し、scripts/render_proof.mjs は実際のヘッドレスブラウザーを使って、その結果をシートタイルのサイズで表示し、実際に描画されたものを報告します。

Qlik Sense May 2026 では、サポート対象の 12 タイプすべてについて、実際のブラウザークライアントでシートタイルのサイズでのレンダリング検証が完了しています：kpi、gauge、barchart、linechart、combochart、piechart、scatterplot、treemap、table、pivot-table、listbox、text-image。

チャートの実際のプロパティ仕様を確認する

スーパーノバが描画を拒否した場合、エラーメッセージからプロパティをリバースエンジニアリングしないでください。チャートによっては、役に立つエラーがまったく発生しません。代わりに、クライアントが書き込む内容を確認します。

node scripts/harvest_client_props.mjs treemap ./truth.json

これにより、読み取り可能なすべてのアプリから、そのタイプのクライアントが作成したオブジェクトをスキャンし、プロパティを出力します。Qlik に付属する監視アプリ（Content／Operations／License Monitor）は、優れた情報源です。最後に残った 2 つの不具合タイプも、推測を何度も繰り返して解決できなかった後、それぞれ 1 回の調査で修正できました。

• treemap では qMode: "K"（ツリーモード。同じ種類の落とし穴として、pivot-table には "P" が必要です）に加え、汎用ビルダーが生成したものより大幅に簡素なプロパティセットが必要でした。Qlik に付属する Content Monitor アプリから取得しました。
• gauge では gaugetype、angle、autoOrientation、paletteProgressColor、segmentInfo が必要でした。これらのプロパティはエラーメッセージに一度も表示されませんでした。gauge はエラーを出さずに失敗するためです。Sense クライアントでこの目的のために作成した gauge から取得しました。

作成したチャートが空白で表示されるかエラーになる場合は、クライアントで作成して情報を取得し、その内容を再現してください。この方法なら数分で済みます。クラッシュメッセージからのリバースエンジニアリングは何時間もかかり、チャートがひっそりと失敗する場合は終わりがありません。

同様のものを作る際に役立つ、手法上の注意点を 3 つ紹介します。

1. オブジェクトは全画面表示ではなく、シートタイルのサイズでレンダリングされます。900×620 では描画できるチャートが、640×150 のタイルでは描画を拒否することがあります。
2. 描画された SVG ノードの数を数えても、証明にはなりません。 壊れたチャートでも凡例は描画されます。そのため、以前のバージョンでは treemap の判定が誤って PASS になりました。
3. 自動判定は参考情報です。スクリーンショットが最終的な判断材料です。 Qlik では、一部のエラー状態がシャドウルート内の SVG テキストとして描画されます。このテキストは、DOM のスクレイピングでも Playwright のテキストロケーターでも安定して検出できませんでした。treemap に「このチャートは表示できません。」と表示されていたにもかかわらず、すべての自動プローブは描画済みと判定しました。render_proof.mjs を SHOTS=<dir> を指定して実行し、画像を確認してください。

認証

どちらも標準的な QSEoW パターンである、2 つのモードを用意しています。ヘッダー認証の仮想プロキシは意図的にサポートしていません。プロキシにアクセスできるクライアントなら誰でも任意の ID を名乗れるため、エージェントツールの基盤として適切ではないからです。

certificate — QMC からエクスポートしたクライアント証明書を使用し、QRS :4242 と Engine :4747 に接続します。サービス間の通信経路であり、すべてのツールを利用できます。QMC からエクスポートするか、POST /qrs/certificatedistribution/exportcertificates を使用してください。

jwt — :443 の JWT 仮想プロキシを介して、署名付きの有効期限付きトークンを使用します。実際のユーザーごとの ID が引き継がれるため、エージェントにユーザー本人として操作させ、そのユーザーのセクションアクセスとセキュリティルールを継承させる場合に適したモードです。

プラットフォーム上の例外が 1 つあります。 Proxy Service REST API（:4243、list_user_sessions／end_user_sessions の背後にあります）が対応しているのは証明書認証のみです。Qlik はこの API に JWT 経由でアクセスする手段を提供していません。この 2 つのツールは、証明書の情報が設定されている場合（QSEOW_CERT_PATH／QSEOW_CERT_KEY_PATH）に、どちらの認証モードでも登録されます。それ以外の場合は tools/list に表示されません。ほかのすべてのツールは、どちらのモードでも同じように利用できます。

JWT と Engine WebSocket（CSWSH）

上記の証明書専用の QPS セッションツール 2 つを除き、どちらのモードでもすべてのツールを利用できます。Engine に対して JWT を機能させるには、特定のハンドシェイクが必要です。間違えやすく、失敗すると本文が空の不透明な 403 が返されるため、ここで説明します。

仮想プロキシは、クロスサイト WebSocket ハイジャック（CSWSH）対策として WebSocket のアップグレードを保護します。アップグレード時に JWT をベアラートークンとして提示しても失敗します。プロキシが求めるのは、ブラウザーが送信する形式です。

1. Authorization: Bearer <jwt> を付けて GET /{prefix}/qps/csrftoken をリクエストします。レスポンスでは、トークンが qlik-csrf-token レスポンスヘッダー（Cookie ではありません）に、セッションが Set-Cookie に格納されて返されます。
2. そのセッション Cookie を送信して、wss://host/{prefix}/app/engineData?qlik-csrf-token=<token> に WebSocket 接続します。ベアラートークンではありません。

サーバーはこの処理を自動的に行い、結果をキャッシュします。キャッシュは単なる最適化ではありません。ベアラー認証を使ったリクエストごとに新しい Qlik セッションが作成され、ユーザーには並列セッション数の上限があるため、呼び出しごとに再認証していると、最終的に Engine から OnMaxParallelSessionsExceeded が返されます。

似たような 403 をデバッグする際の参考として、原因ではないものを挙げます。Origin（ブラウザーはポート付きで送信しますが、受け付けられます）、Host、ポート、トンネルやポートフォワード、xrfkey、仮想プロキシの websocketCrossOriginWhiteList のエントリーです。このリストにはホスト名のみを指定しますが、いずれの場合も結果には影響しませんでした。

スクリプトから設定する場合に確認すべき、実際に起こり得る設定ミスが 1 つあります。QRS API 経由で作成した仮想プロキシでは、loadBalancingServerNodes が空の状態になっています。そのため、サーバーノードを追加するまで、仮想プロキシ経由で Engine にアクセスできません。

プロキシ認証全般をデバッグするには、デバッグログを有効にしてください。%ProgramData%\Qlik\Sense\Proxy\LocalLogConfig.xml を作成し、threshold=debug の QSRollingFileAppender を Audit.Proxy、System.Proxy、Security.Proxy ロガーに割り当ててから、プロキシを再起動します。プロキシが実際に受信したすべてのリクエストヘッダーが記録されるため、ブラウザーで成功するアップグレードとクライアントのリクエストを比較する最も手早い方法です。

テスト用JWTの生成

JWTモードでは、使用するトークンをご自身で用意します。署名済みJWTをQSEOW_JWT（またはQSEOW_JWT_PATH）経由で指定し、JWT仮想プロキシの設定で、どのクレームをQlikのIDに対応付けるかを決定します。一般的な設定では、VPがsubをユーザーIDに、ディレクトリのクレームをユーザーディレクトリに対応付け、VPに貼り付けた証明書を使って署名を検証します。テスト用に有効期間の短いトークンを生成するには、対応する秘密鍵で署名します（RS256）。

// mint-jwt.mjs — node >=20, no deps. Usage: node mint-jwt.mjs > token.jwt
import { createSign } from "node:crypto";
import { readFileSync } from "node:fs";

const key = readFileSync(process.env.JWT_PRIVATE_KEY_PATH, "utf8"); // PEM the VP trusts
const b64u = (o) => Buffer.from(JSON.stringify(o)).toString("base64url");
const now = Math.floor(Date.now() / 1000);
const header = { alg: "RS256", typ: "JWT" };
const payload = {
  sub: process.env.QLIK_USER_ID || "svc_agent",          // → VP "User ID" claim
  directory: process.env.QLIK_USER_DIRECTORY || "QSEOW",  // → VP "User directory" claim
  iat: now,
  exp: now + 3600,
};
const unsigned = `${b64u(header)}.${b64u(payload)}`;
const sig = createSign("RSA-SHA256").update(unsigned).sign(key).toString("base64url");
process.stdout.write(`${unsigned}.${sig}`);

クレーム名は、ご自身の仮想プロキシの属性マッピングに合わせてください。属性マッピングはQMCで設定できます。トークンで指定するIDにはProfessionalライセンス（または適切なライセンス）が割り当てられている必要があります。そうでない場合、エンジンは不明瞭なソケット切断を伴ってOpenDocを拒否します。

信頼モデル — 本番環境で使用する前にお読みください。 JWT仮想プロキシは、すべてのトークンを貼り付けた証明書に照らして検証します。対応する秘密鍵で署名されたトークンだけが受け入れられます。したがって、その秘密鍵はマスター認証情報です。これを持つ人は誰でも、プロキシが対応付ける任意のIDを表すトークンを生成できます。これは、どのSAML／OIDC IDプロバイダーでも同じです。これはJWT SSOに本質的な仕組みであり、このサーバーが追加するものではありません。qseow-mcpはトークンを提示するクライアントにすぎず、プロキシの秘密鍵を持っていなければ、何者にもなりすますことはできません。上記のスニペットを公開しても問題がないのも、同じ理由です。このスニペットで署名できるのは、すでにご自身が管理しているプロキシに対してだけです。したがって、セキュリティは次の4点にかかっています。（1）署名鍵は、それが持つ価値に見合う最高レベルの機密情報として厳重に保護してください。シークレットストアまたはHSMで管理し、リポジトリには絶対に置かず、漏えいが疑われる場合はローテーションしてください。（2）認証は認可とは異なります。生成したIDも、そのユーザーのセキュリティルール、ストリームへのアクセス、セクションアクセスによる制限を受けます。そのため、Qlikユーザーの権限範囲を調整してエージェントの権限範囲を定めてください（セキュリティルールを回避する内部IDとして動作する証明書モードよりもJWTを推奨する理由です）。（3）IDが何らかの操作を行うには、ライセンスの割り当てが必要です。（4）トークンの有効期間は短くしてください（例では1時間後に期限切れになります）。こうしておけば、漏えいしたトークンは鍵とは異なり、自動的に期限切れになります。サーバー自体はデフォルトで読み取り専用のため、有効なIDであっても、有効化しない限りデータを変更することはできません。

本番環境向け JWT の設計

次に当然浮かぶ疑問、「では、実際のユーザーは自分自身として、ほかの誰でもない本人のトークンをどうやって取得するのか？」の答えは、Qlik の外側にあります。JWT プロキシは誰も認証しません。署名キーを持つ者が認証済みであることを信頼するだけです。したがって、本人確認の保証は、（a）実際の認証情報（企業の IdP、MFA など、すでに運用しているもの）で人間を認証し、（b）認証したユーザー本人のアイデンティティだけをクレームに設定するよう構築されたトークン発行者によって担保されます。ユーザーは発行者に対して認証し、キーを保持するのは発行者だけです。ユーザーがキーを目にすることはありません。用途に合った方式を選んでください。

• 対話型の人間 → JWT は使わないでください。 ユーザーを OIDC または SAML の仮想プロキシに誘導し、既存の IdP（Entra ID ／ Okta ／ Google ／ ADFS）で各自のログインと MFA を使って認証します。ユーザーの追加は IdP と Qlik ライセンスの作業となり、トークンの発行やキーの取り扱いは不要です。人間向けには、これが適切なデフォルトです。
• サービスまたはエージェント → 専用の Qlik アイデンティティを使用します。 管理されたサービスユーザー（例：svc_support_agent）を 1 つプロビジョニングし、セキュリティルールで権限を範囲指定して、そのアイデンティティ用のトークンを発行します。エージェントは人間としてではなく、自身として動作します。常時稼働するエージェントには、これが最もすっきりしたパターンです。
• 特定の人に代わって動作するエージェント → 信頼できる中間層を使用します。 小規模なサービスが人間を（IdP 経由で）認証してから、ユーザーごとの有効期限が短い JWT を発行し、エージェントにその人のセクションアクセスをそのまま継承させます。このパターンを選ぶのは、エージェントを通じたユーザーごとのデータ範囲指定が必須の場合に限ってください。

発行者の構築、IdP との接続、適切な範囲指定を最初から正しく設定することが重要です。Terenzi LLC は、サポートエージェントのデプロイの一環として、これらを提供しています。

ソースから実行する

開発用、または Claude Desktop バンドルを自分でビルドする場合 （node mcpb/build.mjs → mcpb/qseow-mcp-<version>.mcpb）。

npm install && npm run build
cp .env.example .env      # fill in host + auth
node dist/index.js        # stdio MCP server

サーバーは ./.env がある場合は自動的に読み込みます（または QSEOW_ENV_PATH で指定されたファイルを読み込みます）。環境にすでに設定されている変数は常に優先されます。MCP クライアント（Claude Desktop ／ Claude Code）に登録する際は、クライアントの env ブロックで変数を渡すか、QSEOW_ENV_PATH に絶対パスを設定してください。作業ディレクトリはクライアントが制御するため、相対パスの ./.env が見つからない場合があります。

デモ

実行可能なデモが examples/ に 3 つあります（GitHub リポジトリのみ。npm パッケージには含まれません）。それぞれに実行手順と、アサーションで検証する trace.mjs が用意されているため、説明用の例ではなく、主張を検証できます。

デモ	内容	ツール実行時間
finance-close	5,000 万ドルの照合不一致の根本原因を特定：KPI → 定義 → リネージ → スクリプト → 修正 → 照合確認	約 5 秒
ops	夜間のリロードが失敗した理由、エンジンが正常かどうか、セキュリティルールのベースラインにドリフトが発生していないかを確認	約 3 秒
builder	概要からシートを作成し、無意味な内容を拒否し、気づきにくい誤ったメジャーを検出して、レンダリング可能かを検証	約 20 秒

cd examples/<demo> && node trace.mjs でいずれかを実行できます。終了コードが 0 以外の場合、アサーションが失敗しています。

稼働中のサイトに対する統合スモークテスト（小規模なデモアプリを作成します。QSEOW_ALLOW_MUTATIONS=true が必要です）。

npm run smoke

注意事項

• エンジンセッションはサーバープロセスごとにキャッシュされ、5 分間アイドル状態が続くと破棄されます。そのため、会話中はツール呼び出しをまたいで選択状態が保持されます。
• QRS の呼び出しごとに、新しい xrfkey が生成されます。
• QSEOW_TLS_VERIFY=false は自己署名されたラボ証明書向けの設定です。本番環境では有効のままにしてください。

商用サポート

qseow-mcp は無料のオープンソースであり、今後もその方針は変わりません。ご自身の環境で動作する Qlik のトラブルシューティング／サポートエージェント（サーバーに加え、エージェント設定、プレイブック、チーム向けの導入支援を含み、導入と検証まで実施）をご希望の場合は、Terenzi LLC にご相談ください。まずは固定料金の読み取り専用アセスメントをご利用いただけます。

Terenzi LLC は Qlik パートナーです。このプロジェクトは独立したものであり、Qlik 製品ではありません（上記の商標に関する注意をご覧ください）。

ライセンス

Apache-2.0 — Copyright 2026 Terenzi LLC。LICENSE と NOTICE をご覧ください。