Qlik Sense MCP

🚀 Qlik Sense MCP Server

Qlik Sense MCP Serverは、Qlik Sense Enterprise APIとの統合を目的としたModel Context Protocol (MCP) サーバーです。MCPプロトコルを通じて、Repository APIとEngine APIの操作に対する統一インターフェースを提供します。

🚀 クイックスタート

概要

Qlik Sense MCP Serverは、Qlik Sense EnterpriseとModel Context Protocolをサポートするシステムを橋渡しします。このサーバーは、アプリケーション、データ、ユーザー、および分析操作に関する21のツールをアプリケーションに提供します。

主な機能

• 統一API：すべてのQlik Sense APIに対する単一のインターフェース
• セキュリティ：証明書ベースの認証サポート
• パフォーマンス：最適化されたクエリとレスポンス処理
• 柔軟性：複数のデータエクスポート形式
• 分析：高度なデータ分析ツール

✨ 主な機能

Repository API (完全に動作します)

コマンド	説明	状態
get_apps	アプリケーションのリストを取得します。	✅
get_app_details	特定のアプリケーションの詳細情報を取得します。	✅
get_app_metadata	REST APIを介してアプリケーションのメタデータを取得します。	✅
get_users	ユーザーのリストを取得します。	✅
get_streams	ストリームのリストを取得します。	✅
get_tasks	タスクのリストを取得します。	✅
start_task	タスクを実行します。	✅
get_data_connections	データ接続を取得します。	✅
get_extensions	拡張機能を取得します。	✅
get_content_libraries	コンテンツライブラリを取得します。	✅

Engine API (完全に動作します)

コマンド	説明	状態
engine_get_doc_list	Engine APIを介してドキュメントのリストを表示します。	✅
engine_open_app	Engine APIを介してアプリケーションを開きます。	✅
engine_get_script	アプリケーションからロードスクリプトを取得します。	✅
engine_get_fields	アプリケーションのフィールドを取得します。	✅
engine_get_sheets	アプリケーションのシートを取得します。	✅
engine_get_table_data	テーブルからデータを抽出します。	✅
engine_get_field_values	頻度情報付きのフィールド値を取得します。	✅
engine_get_field_statistics	包括的なフィールド統計を取得します。	✅
engine_get_data_model	完全なデータモデルを取得します。	✅
engine_create_hypercube	分析用のハイパーキューブを作成します。	✅
engine_create_data_export	複数の形式でデータをエクスポートします。	✅

📦 インストール

uvxを使用したクイックスタート (推奨)

Qlik Sense MCP Serverを使用する最も簡単な方法は、uvxを使用することです。

uvx qlik-sense-mcp-server

このコマンドは、システムのPython環境に影響を与えることなく、最新バージョンを自動的にインストールして実行します。

代替インストール方法

PyPIからのインストール

pip install qlik-sense-mcp-server

ソースからのインストール (開発用)

git clone https://github.com/bintocher/qlik-sense-mcp.git
cd qlik-sense-mcp
make dev

システム要件

• Python 3.12以上
• Qlik Sense Enterprise
• 認証用の有効な証明書
• Qlik Senseサーバーへのネットワークアクセス

セットアップ

1. 証明書のセットアップ

mkdir certs
# Qlik Senseの証明書をcerts/ディレクトリにコピーします

2. 設定ファイルの作成

cp .env.example .env
# .envを自分の設定で編集します

📚 ドキュメント

環境変数 (.env)

# サーバー接続
QLIK_SERVER_URL=https://your-qlik-server.company.com
QLIK_USER_DIRECTORY=COMPANY
QLIK_USER_ID=your-username

# 証明書のパス (絶対パス)
QLIK_CLIENT_CERT_PATH=/path/to/certs/client.pem
QLIK_CLIENT_KEY_PATH=/path/to/certs/client_key.pem
QLIK_CA_CERT_PATH=/path/to/certs/root.pem

# APIポート (標準のQlik Senseポート)
QLIK_REPOSITORY_PORT=4242
QLIK_PROXY_PORT=4243
QLIK_ENGINE_PORT=4747

# SSL設定
QLIK_VERIFY_SSL=false

MCP設定

MCPクライアントの統合用にmcp.jsonファイルを作成します。

{
  "mcpServers": {
    "qlik-sense": {
      "command": "uvx",
      "args": ["qlik-sense-mcp-server"],
      "env": {
        "QLIK_SERVER_URL": "https://your-qlik-server.company.com",
        "QLIK_USER_DIRECTORY": "COMPANY",
        "QLIK_USER_ID": "your-username",
        "QLIK_CLIENT_CERT_PATH": "/path/to/certs/client.pem",
        "QLIK_CLIENT_KEY_PATH": "/path/to/certs/client_key.pem",
        "QLIK_CA_CERT_PATH": "/path/to/certs/root.pem",
        "QLIK_REPOSITORY_PORT": "4242",
        "QLIK_ENGINE_PORT": "4747",
        "QLIK_VERIFY_SSL": "false"
      },
      "disabled": false,
      "autoApprove": [
        "get_apps",
        "get_app_details",
        "get_app_metadata",
        "get_users",
        "get_streams",
        "get_tasks",
        "get_data_connections",
        "get_extensions",
        "get_content_libraries",
        "engine_get_doc_list",
        "engine_open_app",
        "engine_get_script",
        "engine_get_fields",
        "engine_get_sheets",
        "engine_get_table_data",
        "engine_get_field_values",
        "engine_get_field_statistics",
        "engine_get_data_model",
        "engine_create_hypercube",
        "engine_create_data_export"
      ]
    }
  }
}

💻 使用例

サーバーの起動

# uvxを使用する場合 (推奨)
uvx qlik-sense-mcp-server

# インストールされたパッケージを使用する場合
qlik-sense-mcp-server

# ソースからの起動 (開発用)
python -m qlik_sense_mcp_server.server

操作例

アプリケーションリストの取得

# MCPクライアントを介して
result = mcp_client.call_tool("get_apps")
print(f"Found {len(result)} applications")

データ分析用のハイパーキューブの作成

# 販売分析用のハイパーキューブを作成します
result = mcp_client.call_tool("engine_create_hypercube", {
    "app_id": "your-app-id",
    "dimensions": ["Region", "Product"],
    "measures": ["Sum(Sales)", "Count(Orders)"],
    "max_rows": 1000
})

データのエクスポート

# CSV形式でデータをエクスポートします
result = mcp_client.call_tool("engine_create_data_export", {
    "app_id": "your-app-id",
    "table_name": "Sales",
    "format_type": "csv",
    "max_rows": 10000
})

📚 ドキュメント

Repository API関数

get_apps

すべてのQlik Senseアプリケーションのリストを取得します。

パラメーター:

• filter (オプション): アプリケーション検索のフィルタークエリ

戻り値: メタデータ付きのアプリケーションオブジェクトの配列

get_app_details

特定のアプリケーションの詳細情報を取得します。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: 完全なメタデータ付きのアプリケーションオブジェクト

get_app_metadata

データモデルを含む包括的なアプリケーションメタデータを取得します。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: アプリの概要、データモデルの概要、シート情報を含むオブジェクト

get_users

Qlik Senseユーザーのリストを取得します。

パラメーター:

• filter (オプション): ユーザー検索のフィルタークエリ

戻り値: ユーザーオブジェクトの配列

get_streams

アプリケーションストリームのリストを取得します。

パラメーター: なし

戻り値: ストリームオブジェクトの配列

get_tasks

タスク (リロード、外部プログラム) のリストを取得します。

パラメーター:

• task_type (オプション): タイプフィルター ("reload", "external", "all")

戻り値: 実行履歴付きのタスクオブジェクトの配列

start_task

指定されたタスクを実行します。

パラメーター:

• task_id (必須): タスク識別子

戻り値: 実行結果オブジェクト

get_data_connections

データ接続のリストを取得します。

パラメーター:

• filter (オプション): 接続検索のフィルタークエリ

戻り値: データ接続オブジェクトの配列

get_extensions

Qlik Sense拡張機能のリストを取得します。

パラメーター: なし

戻り値: 拡張機能オブジェクトの配列

get_content_libraries

コンテンツライブラリのリストを取得します。

パラメーター: なし

戻り値: コンテンツライブラリオブジェクトの配列

Engine API関数

engine_get_doc_list

Engine APIを介して利用可能なドキュメントのリストを表示します。

パラメーター: なし

戻り値: メタデータ付きのドキュメントオブジェクトの配列

engine_open_app

Engine APIを介してアプリケーションを開き、さらなる操作を行います。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: 後続の操作に使用するアプリケーションハンドルオブジェクト

engine_get_script

アプリケーションからロードスクリプトを取得します。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: スクリプトテキストとメタデータを含むオブジェクト

engine_get_fields

アプリケーションのフィールドのリストを取得します。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: メタデータと統計情報付きのフィールドオブジェクトの配列

engine_get_sheets

アプリケーションのシートを取得します。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: メタデータ付きのシートオブジェクトの配列

engine_get_table_data

アプリケーションのテーブルからデータを抽出します。

パラメーター:

• app_id (必須): アプリケーション識別子
• table_name (オプション): 特定のテーブル名
• max_rows (オプション): 返す最大行数 (デフォルト: 1000)

戻り値: ヘッダーと行情報付きのテーブルデータ

engine_get_field_values

頻度情報付きのフィールド値を取得します。

パラメーター:

• app_id (必須): アプリケーション識別子
• field_name (必須): フィールド名
• max_values (オプション): 返す最大値数 (デフォルト: 100)
• include_frequency (オプション): 頻度データを含める (デフォルト: true)

戻り値: 頻度とメタデータ付きのフィールド値

engine_get_field_statistics

包括的なフィールド統計を取得します。

パラメーター:

• app_id (必須): アプリケーション識別子
• field_name (必須): フィールド名

戻り値: 最小値、最大値、平均値、中央値、最頻値、標準偏差を含む統計分析

engine_get_data_model

テーブルと関連付けを含む完全なデータモデルを取得します。

パラメーター:

• app_id (必須): アプリケーション識別子

戻り値: 関係付け付きのデータモデル構造

engine_create_hypercube

データ分析用のハイパーキューブを作成します。

パラメーター:

• app_id (必須): アプリケーション識別子
• dimensions (必須): 次元フィールドの配列
• measures (必須): 測定式の配列
• max_rows (オプション): 返す最大行数 (デフォルト: 1000)

戻り値: 次元と測定値付きのハイパーキューブデータ

engine_create_data_export

様々な形式でデータをエクスポートします。

パラメーター:

• app_id (必須): アプリケーション識別子
• table_name (オプション): エクスポートするテーブル名
• fields (オプション): エクスポートする特定のフィールド
• format_type (オプション): エクスポート形式 ("json", "csv", "simple")
• max_rows (オプション): エクスポートする最大行数 (デフォルト: 10000)
• filters (オプション): データ選択用のフィールドフィルター

戻り値: 指定された形式のエクスポートデータ

🔧 技術詳細

プロジェクト構造

qlik-sense-mcp/
├── qlik_sense_mcp_server/
│   ├── __init__.py
│   ├── server.py          # メインのMCPサーバー
│   ├── config.py          # 設定管理
│   ├── repository_api.py  # Repository APIクライアント
│   └── engine_api.py      # Engine APIクライアント (WebSocket)
├── certs/                 # 証明書 (git管理外)
│   ├── client.pem
│   ├── client_key.pem
│   └── root.pem
├── .env.example          # 設定テンプレート
├── .env                  # あなたの設定
├── mcp.json.example      # MCP設定テンプレート
├── pyproject.toml        # プロジェクトの依存関係
└── README.md

システムコンポーネント

QlikSenseMCPServer

MCPプロトコルの操作、ツールの登録、およびリクエストのルーティングを処理するメインサーバークラス。

QlikRepositoryAPI

アプリケーション、ユーザー、タスク、およびメタデータ管理を含むRepository API操作のHTTPクライアント。

QlikEngineAPI

データ抽出、分析、およびハイパーキューブ作成を含むEngine API操作のWebSocketクライアント。

QlikSenseConfig

環境変数、証明書パス、および接続設定を処理する設定管理クラス。

🔧 開発

開発環境のセットアップ

プロジェクトには、一般的な開発タスク用のMakefileが含まれています。

# 開発環境のセットアップ
make dev

# 利用可能なすべてのコマンドを表示
make help

# パッケージのビルド
make build

バージョン管理とリリース

Makefileコマンドを使用してバージョン管理を行います。

# パッチバージョンを上げてPRを作成
make version-patch

# マイナーバージョンを上げてPRを作成
make version-minor

# メジャーバージョンを上げてPRを作成
make version-major

これにより、自動的に以下のことが行われます。

1. pyproject.tomlのバージョンを上げる
2. 新しいブランチを作成する
3. 変更をコミットする
4. ブランチをプッシュしてPRを作成する

公開プロセス

1. バージョンを上げたPRをマージする
2. 自動的なPyPI公開をトリガーするためにタグを作成してプッシュする:

   git tag v1.0.1
   git push origin v1.0.1
   

3. GitHub Actionsが自動的にビルドしてPyPIに公開する

Git履歴のクリーンアップ

もしクリーンなGit履歴から始める必要がある場合は、以下のコマンドを使用します。

make git-clean

警告: これにより、Git履歴が完全に削除されます！

新しい機能の追加

1. server.pyにツール定義を追加する

# In handle_list_tools()
{"name": "new_tool", "description": "Tool description", "inputSchema": {...}}

2. server.pyにハンドラーを追加する

# In handle_call_tool()
elif name == "new_tool":
    result = await asyncio.to_thread(self.api_client.new_method, arguments)
    return [TextContent(type="text", text=json.dumps(result, indent=2))]

3. APIクライアントにメソッドを実装する

# In repository_api.py or engine_api.py
def new_method(self, param: str) -> Dict[str, Any]:
    """Method implementation."""
    # Implementation code
    return result

コード標準

プロジェクトは標準的なPython規則を使用しています。パッケージをビルドしてテストします。

make build   # パッケージのビルド

🔧 トラブルシューティング

一般的な問題

証明書エラー

SSL: CERTIFICATE_VERIFY_FAILED

解決策:

• .envの証明書パスを確認する
• 証明書の有効期限を確認する
• テスト用にQLIK_VERIFY_SSL=falseを設定する

接続エラー

ConnectionError: Failed to connect to Engine API

解決策:

• ポート4747のアクセス可能性を確認する
• サーバーURLの正しさを確認する
• ファイアウォール設定を確認する

認証エラー

401 Unauthorized

解決策:

• QLIK_USER_DIRECTORYとQLIK_USER_IDを確認する
• Qlik Senseにユーザーが存在することを確認する
• ユーザーの権限を確認する

診断

Repository APIのテスト

python -c "
from qlik_sense_mcp_server.config import QlikSenseConfig
from qlik_sense_mcp_server.repository_api import QlikRepositoryAPI
config = QlikSenseConfig.from_env()
api = QlikRepositoryAPI(config)
print('Apps:', len(api.get_apps()))
"

Engine APIのテスト

python -c "
from qlik_sense_mcp_server.config import QlikSenseConfig
from qlik_sense_mcp_server.engine_api import QlikEngineAPI
config = QlikSenseConfig.from_env()
api = QlikEngineAPI(config)
api.connect()
print('Docs:', len(api.get_doc_list()))
api.disconnect()
"

🔧 パフォーマンス

最適化の推奨事項

1. フィルターを使用してデータ量を制限する
2. 頻繁に使用するクエリの結果をキャッシュする
3. max_rowsパラメーターで結果のサイズを制限する
4. メタデータにはRepository APIを使用する (Engine APIより高速)

ベンチマーク

操作	平均時間	推奨事項
get_apps	0.5秒	フィルターを使用する
get_app_metadata	2 - 5秒	結果をキャッシュする
engine_create_hypercube	1 - 10秒	サイズを制限する
engine_create_data_export	5 - 30秒	ページングを使用する

🔧 セキュリティ

推奨事項

1. 証明書を安全に保管する - gitから除外する
2. 機密データには環境変数を使用する
3. Qlik Senseでユーザー権限を制限する
4. 証明書を定期的に更新する
5. APIアクセスを監視する

アクセス制御

QMCで最小限の必要な権限を持つユーザーを作成します。

• アプリケーションを読み取る
• 必要に応じてタスクを実行する
• Engine APIにアクセスする

📄 ライセンス

MIT License

Copyright (c) 2025 Stanislav Chernov

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---

プロジェクトの状態: 本番環境で使用可能 | 21/21のコマンドが動作しています | v1.0.0

インストール方法: uvx qlik-sense-mcp-server