Qlik Sense Mcp Server

Qlik Sense MCP Server

Qlik Sense Enterprise 向けの Model Context Protocol サーバーです。Qlik の Repository（HTTP）および Engine（WebSocket）API を28 個の MCP ツールとして公開し、LLM クライアントが単一の統一インターフェースを通じてアプリを見つけ、データモデルを調査し、データをクエリし、リロードタスクを管理できるようにします。JWT モードおよびフォーム（ログイン／パスワード）モードでは、リロードタスク用の 14 個のツールはデフォルトで非表示です。QRS のタスク管理には QMC の管理者ロールが必要ですが、JWT を使うアナリストやフォームログインのユーザーには通常その権限がないためです。これは認証方法ではなく、ID に紐づく権限です。その権限を持つ ID で使用する場合は、QLIK_TASK_TOOLS=true にすると有効になります。

同梱内容

分野	ツール	用途
Repository（アプリとメタデータ）	get_about、get_apps、get_app_details	アプリの検出、テーブルとフィールドおよびカーディナリティの一覧表示
Engine（データとスクリプト）	engine_query、engine_create_hypercube、get_app_script、get_app_variables、get_app_sheets、get_app_sheet_objects、get_app_object、search_app、get_app_field、engine_get_field_range、get_app_field_statistics	データのクエリ、ロードスクリプトの読み取り、ビジュアライゼーションの一覧表示、フィールド値の調査
リロードタスク (デフォルトでは証明書モード。他のモードではオプトインが必要です。下記を参照)	get_tasks、get_task_details、get_task_dependencies、get_task_schedule、get_task_executions、get_task_script_log、get_failed_tasks_with_logs、start_task、create_task、update_task、delete_task、create_task_schedule、update_task_schedule、delete_task_schedule	リロードタスクの調査、実行、管理

説明付きの全リスト：docs/tools.md。

主な分析呼び出しでは、Qlik の構文ではなく質問を指定します。

// engine_query — "revenue by region for 2024, biggest first"
{
  "app_id": "<app guid>",
  "group_by": ["region_name"],
  "metrics":  [{"field": "amount", "agg": "sum", "label": "Revenue"}],
  "filters":  [{"field": "order_date", "period": "2024"}],
  "sort_by": "Revenue",
  "limit": 10
}

サーバーはセット分析を作成し、フィルターで何かが選択されていることを確認したうえで、period_check（結果に実際に含まれる最も古い日付と最新の日付）とともに回答します。これにより、フィルターが適用されなかった場合に、もっともらしい数値の陰に隠れず、問題を確認できます。個別の質問は queries として 1 回の呼び出しにまとめられ、3 回の往復で処理されます。

より複雑な質問も同じ形式で扱えます。全体に占める割合を求める場合は、分子を絞り込み、分母には絞り込みを適用しません。

{
  "group_by": ["region_name"],
  "metrics": [{"label": "Share", "op": "divide", "of": [
    {"field": "amount", "agg": "sum",
     "filters": [{"field": "category", "values": ["Alpha"]}]},
    {"field": "amount", "agg": "sum", "total": true}]}]
}

同じ形式で、集計に対する集計（"inner_agg": "sum", "per": "order_id", "agg": "median"）、ある年に購入し翌年には購入しなかった顧客（matching／not_matching）、ブックマークを対象にしたカウントや選択を無視するカウント（scope）、任意のフィールドでの値の保持、除外、追加、積集合も指定できます。

アプリ独自のマスター指標は再構築せず、名前で指定します（"measures": [{"master": "Revenue"}]）。クエリのフィルターは、その指標の外側のセットとして適用されます。

engine_create_hypercube も同じ形式を受け取り、型付き形式では表現できない計算では、式を手動で記述します。

クイックスタート

uvx qlik-sense-mcp-server

サーバーはストリーム可能な HTTP モードで http://127.0.0.1:8000/mcp に起動します。環境変数で設定できます。 詳しくは docs/configuration.md をご覧ください。

stdio モード（レガシー MCP トランスポート）を使用するには、--stdio を指定してください。

次の 3 種類の認証モードに対応しています。クライアント証明書（レガシー、 QRS へのフルアクセス）、仮想プロキシ経由の JWT（アナリストごと、ディスク上に シークレットを保存しない）、および「Form based」仮想プロキシを使った ログイン／パスワード認証（標準搭載の Windows 資格情報ログインページなど）です。設定方法については、 docs/AUTH_JWT.md と docs/AUTH_FORM.md をご覧ください。

ドキュメント

ドキュメント	内容
docs/installation.md	要件、uvx／pip／ソースからのインストール、証明書の設定
docs/configuration.md	すべての QLIK_* 環境変数、.env のサンプル、MCP クライアント設定スニペット
docs/AUTH_JWT.md	仮想プロキシ経由の JWT 認証：キーの生成、仮想プロキシの設定、QLIK_JWT_TOKEN の使用方法
docs/AUTH_FORM.md	「Form based」仮想プロキシ経由のログイン／パスワード認証：ログインフローの仕組み、QLIK_PASSWORD の使用方法、デフォルト以外のログインページ向けのオーバーライド
docs/usage.md	トランスポート、サーバーの起動コマンド、推奨される呼び出し順序、このサーバーが適用する厳格な上限
docs/tools.md	全 28 ツールの一覧、レスポンス／エラーのエンベロープ、エラーカテゴリ
docs/architecture.md	プロジェクト構成、コンポーネント、接続のキャッシュ、厳密な ID 照合、2 段階のタイムアウト
docs/development.md	make のターゲット、テスト、バージョン管理、新しいツールの追加方法
docs/troubleshooting.md	よくあるエラー、ハイパーキューブの計画失敗、詳細ログ、設定のセルフテスト
docs/llm-behaviour.md	モデルが実際にこのサーバーをどう使うか：質問あたりの呼び出し回数、誤りやすい箇所、セッションの上限、適切なベンチマーク方法を測定
CHANGELOG.md	リリースノート

主な情報

• 誤ったクエリは回答されず、拒否されます。 Qlik は不明なフィールド名を値が 0 の式として評価するため、誤字を含む項目でグループ化したハイパーキューブは、合計値だけを含む 1 行を返していました。もっともらしい数値が返る一方で、誤りを示すものは何もありませんでした。実行前に、すべてのクエリを Engine で検証します。ExpandExpression で変数を解決し、CheckExpression で構文と不明な名前を報告し、GetFieldsFromExpression でセット修飾子が実際にフィルタリングするフィールドを報告します。この 4 つのチェックは 1 回のバッチで約 4ms かかります。最小のハイパーキューブでも 75ms かかります。

• 期間フィルターは推測せず、実測します。 セット修飾子内の比較は、Qlik が値を表示するテキストに対して実行されます。そのため、シリアル番号の範囲は、01.01.2024 と表示されるフィールドでは 0 件を返し、45292 と表示されるフィールドでは機能しますが、どちらの場合もエラーは発生しません。期間をフィルターとして指定すると、サーバーはそのフィールド独自の表示形式で範囲を記述し、参照件数と照合します。うまくいかなければ数値範囲に切り替え、さらに必ず機能する形式に切り替えます。また、結果が実際に対象とする期間を報告し、シフトしたカレンダーによってその期間外のデータに及んだ場合はそのことも報告します。

• フィルターは作成者のメジャーにも適用されます。 期間を指定した {"master": "Revenue"} は、メジャーの前に外部セットを置いた {&<period>} [Revenue] として計算されます。また、フィルター対象のフィールド自体を設定するメジャーや、独自のセットに対して集計するメジャーなど、フィルターが適用されない場合は、そのメジャーを応答で示します。

• 値の表記は一貫しています。 クエリ結果の日付は、get_app_details のサンプル値や engine_get_field_range の境界値と同じく、Qlik での表示テキストとして読み取れます。

• フィールド名は必ず角括弧で囲みます。 Тип ставки のようにそのまま記述すると、Qlik のパーサーは 2 つのトークンとして読み取り、「式の後に不要な文字があります：'ставки'」となります。そのため、以前は Qlik 自身なら問題なく実行できるクエリが拒否されていました。

• 行ではなくグループを集計します。 per と inner_agg を使うと、「案件ごとに合計し、その後、案件全体で 85 パーセンタイルを求める」と指定できます。これは行単位のパーセンタイルとは異なる問いであり、結果の数値も異なります。

• メジャー自身で対象を絞り込めます。 メジャー独自の filters はクエリのフィルターより優先されるため、KPI の分子と分母を 1 つの回答で返せます。

• オブジェクトの内容を明示します。 get_app_sheet_objects は各オブジェクトについて、ディメンション、式を含むメジャー、依存する条件や変数、フィルターやボタンの動作を 1 行で示します。また、マスターアイテム経由で参照されるフィールドや、フィルターパネルのリストボックス内のフィールドも含む fields_used を返します。そのため、「このシートは何を扱っているのか」を計算なしで 1 回の呼び出しで確認できます。

• ページングは Qlik 側で行い、取得後には行いません。 アプリとタスクの一覧は /{entity}/table を skip／take とともに読み込み、総数は /{entity}/count から取得します。そのため、QRS のレコード上限を超えたデータが欠落せず、total_found には実際の総数が入ります。フィールド検索とフィールドのページングも同様に Engine で行います。旧方式のローカルスキャンでは一致する値を見つけられなかった、異なる値が 200,000 件あるフィールドで検証済みです。

• 失敗が空の回答として返ることはありません。 QRS 500、接続拒否、Engine エラーは、以前は []、""、または「スケジュールなし」として返されていました。これでは Qlik に問題がなく、単にデータが空であるかのように見えていました。現在は、どの経路でも error_category と元の原因を返します。

• 列名だけでなく、列の意味も示します。 ロードスクリプトでコメントが付けられたフィールドとテーブル（COMMENT FIELD／COMMENT TABLE）は、そのテキストが get_app_details では comment に、get_app_field では field_comment に渡されます。そのため、モデルは列名から意味を推測するのではなく、列の意味を読み取れます。1.7.2 で追加されました。

• どちらの MCP SDK 系列でも動作します。 SDK 2.0 では FastMCP が削除されました。サーバーはインポート時に MCPServer（2.x）または FastMCP（1.x）を選択するため、mcp>=1.8.0,<3.0.0 のすべてで動作します。両系列がテストスイートの対象であり、稼働中の Qlik アプリを使ったエンドツーエンドの検証も済んでいます。

• 1 回の呼び出しで上位 N 件を取得。 engine_create_hypercube では、sort_by（メジャーのラベル、メジャーの式、またはディメンション フィールド）、sort_order（desc / asc）、limit を指定できるため、「GGR が最も高い 10 クライアント」を 1 回のリクエストで取得できます。v1.6.0 より前は、メジャーによる 並べ替えが何も行われない状態でした。qInterColumnSortOrder がディメンションに 固定されていたため、サーバーは最大値の行ではなく、アルファベット順で先頭の 行を返していました。

• NULL グループは非表示ではなく表示されます。 グループ化フィールドに値がないファクトは Qlik の "-" 行にまとめられます。この行には大きな合計が含まれていることが多く、上位 N 件の 先頭になる場合があります。グループ化する値がないファクトもファクトであるため、デフォルトでは 含まれます。exclude_null_dimensions=true を指定すると除外されます。

• コンパクトで LLM に適した結果。 ハイパーキューブのレスポンスは、 実数値を含む columns + rows に加え、grand_total と ステップごとの timings で構成されます。Qlik の完全なレイアウトを取得するには include_raw_layout=true を指定します。

• エラーには失敗したクエリが示されます。 タイムアウトを含むすべてのエラーレスポンスには、 送信された正確な引数とともに tool と request が含まれます。

• JWT／フォームモードでは、役に立たないツールをデフォルトで減らします。 リロードタスクの 管理には QRS の管理者権限が必要です。これは認証方式ではなく QMC のロールであるため、 対応する 14 個のツールは、証明書モードではデフォルトで有効、JWT／フォームモードでは 無効になります。証明書では 28 個、JWT またはログイン／パスワードでは 14 個のツールを 利用できます。JWT／フォームモードでも有効にするには、必要な権限があることを確認した ID で QLIK_TASK_TOOLS=true を設定します。

• サーバーごとに Qlik セッションは 1 つです。 Qlik のユーザーごとの上限（デフォルトで 5）は プロキシセッションをカウントします。JWT／フォームモードでは、WebSocket 接続より前に セッションの初期化自体によって 1 つ作成されます。そのため、サーバーは一度だけ初期化し、 すべての呼び出しで同じセッションを再利用します。ループ内でサーバーを再起動すると上限に 達しますが、クエリの数によって上限に達することはありません。

• 仮想プロキシ経由の JWT 認証。 証明書のパスの代わりに QLIK_JWT_TOKEN を設定すると、サーバーはトークンに埋め込まれたアナリストとして、すべての Repository および Engine 呼び出しを認証します。ホスト上に証明書や秘密鍵を置く必要はありません。 従来の証明書モードに変更はなく、QRS への完全なアクセスには引き続き必要です。 セットアップガイド：docs/AUTH_JWT.md。

• 「Form based」仮想プロキシ経由のログイン／パスワード認証。 証明書または JWT の代わりに QLIK_PASSWORD（および QLIK_USER_ID と、任意で QLIK_USER_DIRECTORY）を設定すると、サーバーはブラウザーと同じ方法でプロキシの ログインページにログインします。その後、独自の初期化を行う JWT モードとまったく同じように、 取得したセッションクッキーを再利用します。セットアップガイド： docs/AUTH_FORM.md。

• Engine WebSocket 接続をキャッシュします。 アプリを開いた後、同じ app_id に対する 以降のすべてのツール呼び出しでは、同じ WebSocket と開いたドキュメントを再利用します。 app_id を切り替えると、同じソケット上で古いドキュメントを閉じ、新しいドキュメントを開きます。 接続が切断された場合は、透過的に再接続します。実装： engine/connection.py および docs/architecture.md。

• デフォルトのトランスポートは Streamable HTTP です。 サーバーは長時間実行される プロセスであり、複数の MCP クライアントが並行して通信できます。従来の stdio モードも --stdio で引き続き使用できます。

• tool_call_seconds は、各ツールレスポンスの先頭のキーとして挿入されます。これは 呼び出しの実時間をミリ秒で示します。処理の遅いツールの特定に利用できます。

• ハイパーキューブの厳格な上限。 engine_create_hypercube は、 max_rows > 5000 または columns * max_rows > 9900 のリクエストを直ちに拒否し、 set analysis や上位 N 件のパターンを示すヒント付きの構造化エラーを返します。Qlik Engine 自体も、1 ページのセル数が 10000 を超えると エラー 7009 calc-pages-too-large を返します。

• タイムアウト設定は 2 つです。 QLIK_WS_TIMEOUT（デフォルトは 180.0 秒）は WebSocket ハンドシェイクとすべての Engine API 呼び出しの両方を制御します。 QLIK_TOOL_TIMEOUT（デフォルトは 240.0）はツール呼び出し全体の時間を制限するため、 クライアントがタイムアウトする前に、処理の遅い呼び出しを明確なエラーで終了できます。

要件

• Python 3.12（このバージョンを対象にパッケージをビルドおよびテストしています。詳細は pyproject.toml を参照してください）
• Qlik Sense Enterprise（Repository はポート 4242、Engine はポート 4747 — 標準ポート）
• Qlik Sense ノードから取得したクライアント証明書、秘密鍵、ルート CA（証明書モードのみ。JWT モードとフォームモードでは、トークンまたはパスワード以外にディスク上のファイルは不要です）
• このサーバーを実行するホストから Qlik へのネットワークアクセス

免責事項

このプロジェクトは、コミュニティによって独立して開発されたインテグレーションです。Qlik Technologies Inc.、QlikTech International AB、その他の Qlik 関連企業とは一切提携しておらず、承認、後援、サポートを受けていません。「Qlik」、「Qlik Sense」、「QlikView」および関連するすべての製品名は、それぞれの所有者の商標です。

このプロジェクトで使用している Qlik Sense API、ポートの割り当て、エラーコード、プロトコルの動作、使用パターンに関する情報は、Qlik Developer Portal（help.qlik.com、qlik.dev）、Qlik Community フォーラム、その他の公開ドキュメントなど、一般に公開されている情報源のみから取得しています。専有情報、機密情報、リバースエンジニアリングによる資料は使用していません。

ライセンス

MIT © 2025-2026 Stanislav Chernov