Qlik Sense MCP

🚀 Qlik Sense MCP 服務器

Qlik Sense MCP 服務器用於集成 Qlik Sense Enterprise API，通過 MCP 協議為存儲庫 API 和引擎 API 操作提供統一接口，能連接 Qlik Sense Enterprise 與支持模型上下文協議的系統，為應用程序、數據、用戶和分析操作提供 21 種工具。

🚀 快速開始

Qlik Sense MCP 服務器是連接 Qlik Sense Enterprise 和支持模型上下文協議系統的橋樑。服務器為應用程序、數據、用戶和分析操作提供了 21 種工具。

關鍵特性

• 統一 API：為所有 Qlik Sense API 提供單一接口。
• 安全性：支持基於證書的身份驗證。
• 高性能：優化查詢和響應處理。
• 靈活性：支持多種數據導出格式。
• 分析功能：提供高級數據分析工具。

✨ 主要特性

存儲庫 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	獲取內容庫	✅

引擎 API（完全可用）

命令	描述	狀態
engine_get_doc_list	通過引擎 API 列出文檔	✅
engine_open_app	通過引擎 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 服務器最簡單的方法是使用 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 文件

💻 使用示例

啟動服務器

# 使用 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"找到 {len(result)} 個應用程序")

高級用法

創建數據分析超立方體

# 創建用於銷售分析的超立方體
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
})

📚 詳細文檔

存儲庫 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

獲取內容庫列表。 參數：無 返回值：內容庫對象數組。

引擎 API 函數

engine_get_doc_list

通過引擎 API 列出可用文檔。 參數：無 返回值：包含元數據的文檔對象數組。

engine_open_app

通過引擎 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  # 存儲庫 API 客戶端
│   └── engine_api.py      # 引擎 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

用於存儲庫 API 操作的 HTTP 客戶端，包括應用程序、用戶、任務和元數據管理。

QlikEngineAPI

用於引擎 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 中添加工具定義

# 在 handle_list_tools() 中
{"name": "new_tool", "description": "工具描述", "inputSchema": {...}}

2. 在 server.py 中添加處理程序

# 在 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 客戶端中實現方法

# 在 repository_api.py 或 engine_api.py 中
def new_method(self, param: str) -> Dict[str, Any]:
    """方法實現。"""
    # 實現代碼
    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 中。
• 驗證用戶權限。

診斷方法

測試存儲庫 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('應用程序數量:', len(api.get_apps()))
"

測試引擎 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('文檔數量:', len(api.get_doc_list()))
api.disconnect()
"

📈 性能優化

優化建議

1. 使用過濾器 來限制數據量。
2. 緩存結果 以用於頻繁使用的查詢。
3. 使用 max_rows 參數 限制結果大小。
4. 使用存儲庫 API 來獲取元數據（比引擎 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 中創建具有最小所需權限的用戶：

• 讀取應用程序
• 執行任務（如果需要）
• 訪問引擎 API

📄 許可證

本項目採用 MIT 許可證。

版權所有 (c) 2025 Stanislav Chernov

特此免費授予任何獲得本軟件及相關文檔文件（“軟件”）副本的人不受限制地處理本軟件的權利，包括但不限於使用、複製、修改、合併、發佈、分發、再許可和/或出售軟件副本的權利，並允許向其提供軟件的人這樣做，但須遵守以下條件：

上述版權聲明和本許可聲明應包含在所有副本或軟件的重要部分中。

軟件按“原樣”提供，不附帶任何形式的明示或暗示保證，包括但不限於適銷性、特定用途適用性和不侵權的保證。在任何情況下，作者或版權持有人均不對因合同、侵權或其他方式引起的任何索賠、損害或其他責任負責，無論其與軟件或軟件的使用或其他交易有何關聯。

---

項目狀態：可用於生產環境 | 21/21 個命令可用 | v1.0.0

安裝命令：uvx qlik-sense-mcp-server