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