🚀 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 服务器的网络
配置步骤
- 设置证书
mkdir certs
# 将您的 Qlik Sense 证书复制到 certs/ 目录
- 创建配置文件
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
这将自动执行以下操作：
- 在
pyproject.toml中增加版本号。 - 创建一个新分支。
- 提交更改。
- 推送分支并创建 PR。
发布流程
- 合并版本更新的 PR
- 创建并推送标签 以触发自动 PyPI 发布：
git tag v1.0.1 git push origin v1.0.1 - GitHub Actions 将自动构建并发布到 PyPI。
清理 Git 历史
如果您需要清理 git 历史记录：
make git-clean
警告：这将完全删除 git 历史记录！
添加新功能
- 在 server.py 中添加工具定义
# 在 handle_list_tools() 中
{"name": "new_tool", "description": "工具描述", "inputSchema": {...}}
- 在 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))]
- 在 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()
"
📈 性能优化
优化建议
- 使用过滤器 来限制数据量。
- 缓存结果 以用于频繁使用的查询。
- 使用
max_rows参数 限制结果大小。 - 使用存储库 API 来获取元数据（比引擎 API 更快）。
基准测试
| 操作 | 平均时间 | 建议 |
|---|---|---|
| get_apps | 0.5 秒 | 使用过滤器 |
| get_app_metadata | 2 - 5 秒 | 缓存结果 |
| engine_create_hypercube | 1 - 10 秒 | 限制大小 |
| engine_create_data_export | 5 - 30 秒 | 使用分页 |
🔒 安全建议
安全建议
- 安全存储证书 - 不要将其包含在 git 中。
- 使用环境变量 来存储敏感数据。
- 在 Qlik Sense 中 限制用户权限。
- 定期更新证书。
- 监控 API 访问。
访问控制
在 QMC 中创建具有最小所需权限的用户：
- 读取应用程序
- 执行任务（如果需要）
- 访问引擎 API
📄 许可证
本项目采用 MIT 许可证。
版权所有 (c) 2025 Stanislav Chernov
特此免费授予任何获得本软件及相关文档文件（“软件”）副本的人不受限制地处理本软件的权利，包括但不限于使用、复制、修改、合并、发布、分发、再许可和/或出售软件副本的权利，并允许向其提供软件的人这样做，但须遵守以下条件：
上述版权声明和本许可声明应包含在所有副本或软件的重要部分中。
软件按“原样”提供，不附带任何形式的明示或暗示保证，包括但不限于适销性、特定用途适用性和不侵权的保证。在任何情况下，作者或版权持有人均不对因合同、侵权或其他方式引起的任何索赔、损害或其他责任负责，无论其与软件或软件的使用或其他交易有何关联。
项目状态：可用于生产环境 | 21/21 个命令可用 | v1.0.0
安装命令：uvx qlik-sense-mcp-server