Qlik Sense Mcp Server

Qlik Sense MCP 服务

面向 Qlik Sense Enterprise 的 Model Context Protocol 服务。它将 Qlik 的 Repository（HTTP）和 Engine（WebSocket）API 封装为 28 个 MCP 工具，让大模型客户端能够通过统一接口发现应用、检查数据模型、查询数据并管理重新加载任务。在 JWT 和表单（登录名/密码）模式下，默认隐藏 14 个重新加载任务工具：QRS 任务管理需要 QMC 中的管理员角色，而 JWT 分析员或表单登录用户通常没有该角色。这取决于身份本身，而不是身份验证方式，因此对于具有相应权限的身份，可设置 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 提交多个相互独立的问题，并共用三次往返请求。

更复杂的问题也使用相同的形式。计算总体中的占比，其中分子缩小范围，分母不变：

{
  "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

服务以 Streamable HTTP 模式启动，地址为 http://127.0.0.1:8000/mcp。通过环境 变量进行配置——请参阅 docs/configuration.md。

如需使用 stdio 模式（旧版 MCP 传输），请传入 --stdio。

支持三种身份验证模式：客户端证书（旧版， 完全访问 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 匹配、双层超时
docs/development.md	make 目标、测试、版本管理、如何添加新工具
docs/troubleshooting.md	常见错误、超立方体规划失败、详细日志、自检配置
docs/llm-behaviour.md	模型实际如何使用本服务（实测）：每个问题的调用次数、出错之处、会话限制、如何进行诚实的基准测试
CHANGELOG.md	发行说明

关键事实

• 错误的查询会被拒绝，而不是返回答案。 Qlik 会将未知字段名视为值为 0 的表达式，因此按拼写错误的字段分组的超立方体会返回一行总计——这是一个看似合理、却无法表明查询有误的数字。每个查询都会在运行前由 Engine 检查：ExpandExpression 用于解析变量，CheckExpression 用于报告语法错误和未知名称，GetFieldsFromExpression 用于报告集合修饰符实际筛选的字段。四项检查在一次批处理中耗时约 4ms，而最小的超立方体需要 75ms。

• 时间段筛选会经过测量，而不是凭空假定。 集合修饰符中的比较依据的是 Qlik 显示的值文本，因此序列号范围用于显示为 01.01.2024 的字段时会返回 0，用于显示为 45292 的字段时则会正常工作——无论哪种情况都不会报错。将时间段指定为筛选条件后，服务会按字段自身的显示格式将其写为范围，与参考计数进行核对，随后回退到数值范围，再回退到始终有效的形式；并报告结果实际涵盖的时间段，以及偏移后的日历导致该时间段包含其外部事实数据的情况。

• 筛选条件会作用于作者定义的度量。 带有时间段的 {"master": "Revenue"} 会被计算为 {&<period>} [Revenue]，即在度量前添加外部集合；回复还会指出度量本身设置了筛选字段，或在自己的集合上进行计数，因此筛选条件不会传递到该度量。

• 同一个值，只用一种写法。 查询结果中的日期会显示为 Qlik 展示的文本，与 get_app_details 中的示例值和 engine_get_field_range 返回的边界值一致。

• 字段名始终用方括号括起来。 不加方括号的 Тип ставки 会被 Qlik 的解析器读作两个词元——“表达式后有多余内容：'ставки'”——过去因此会拒绝 Qlik 自己能够顺利运行的查询。

• 按分组聚合，而不是按行聚合。 per 和 inner_agg 表示“先按问题求和，再计算各问题的第 85 百分位数”，这与按行计算百分位数是不同的问题，因此结果也不同。

• 度量可以缩小自身范围。 度量自身的 filters 会覆盖查询的筛选条件，因此 KPI 可以在同一个答案中包含分子和分母。

• 对象会说明自身展示的内容。 get_app_sheet_objects 为每个对象提供一行信息——包括其维度、带表达式的度量、所依赖的条件和变量、筛选器或按钮的作用，以及 fields_used；其中还包括通过主项目引用的字段，以及筛选窗格列表框中的字段——因此只需一次调用，就能了解“此工作表使用了什么”，无需进行任何计算。

• 由 Qlik 负责分页，而不是事后处理。 应用和任务列表通过 /{entity}/table 配合 skip/take 读取，并通过 /{entity}/count 获取总数，因此不会遗漏 QRS 记录限制之外的内容，total_found 也是真实总数。字段搜索和字段分页同样在 Engine 中进行——已在一个包含 200,000 个不同值的字段上验证；旧的本地扫描根本无法找到匹配项。

• 失败绝不会被伪装成空答案。 QRS 500 错误、连接被拒或 Engine 错误过去会以 []、"" 或“无计划”的形式返回，让人以为 Qlik 中的内容已整齐地清空。现在所有这类情况都会返回 error_category 和原始原因。

• 说明列的含义，而不仅仅是列名。 在加载脚本中添加注释的字段和表（COMMENT FIELD / COMMENT TABLE）会将相应文本作为 comment 传入 get_app_details，并作为 field_comment 传入 get_app_field，让模型了解列的含义，而不是根据名称猜测。此功能新增于 1.7.2。

• 兼容两代 MCP SDK。 SDK 2.0 移除了 FastMCP；服务现在会在导入时选择 MCPServer（2.x）或 FastMCP（1.x），因此 mcp>=1.8.0,<3.0.0 均可运行。测试套件涵盖两代 SDK，并已通过实时 Qlik 应用完成端到端验证。

• 单次调用执行排名查询（Top-N）。 engine_create_hypercube 接受 sort_by（度量标签、度量表达式或维度字段）、sort_order （desc / asc）和 limit，因此“GGR 最高的 10 个客户端”只需一次请求。v1.6.0 之前，按度量排序会悄无声息地失效——qInterColumnSortOrder 被硬编码为维度，因此服务返回的是按字母顺序排列的前几行，而非数值最大的行。

• NULL 分组会显示，而非隐藏。 分组字段没有值的事实会归并到 Qlik 的 "-" 行中，该行通常包含较大的总数，可能在 Top-N 中排第一。默认会保留该行——分组值缺失的事实仍然是事实——设置 exclude_null_dimensions=true 可将其排除。

• 结果精简且适合大模型。 超立方体响应包含 columns + rows 和实际数值，以及 grand_total 和每个步骤的 timings。传入 include_raw_layout=true 可获取完整的 Qlik 布局。

• 错误会指出失败的查询。 每条错误回复（包括超时）都会回显 tool 和 request，其中包含发送时的确切参数。

• 默认情况下，JWT/表单模式下无用工具更少。 重新加载任务管理需要 QRS 管理员权限——这是 QMC 角色的要求，而非身份验证方式的属性——因此这 14 个工具在证书模式下默认启用，在 JWT/表单模式下默认关闭：使用证书时有 28 个工具，使用 JWT 或登录名/密码时有 14 个工具。设置 QLIK_TASK_TOOLS=true 也会在 JWT/表单模式下启用这些工具，前提是已验证该身份拥有相应权限。

• 每台服务只建立一个 Qlik 会话。 Qlik 的每用户限制（默认 5 个）统计的是代理会话；在 JWT/表单模式下，即使尚未建立任何 WebSocket，启动会话时也会创建一个会话。因此，服务会启动一次并在每次调用中复用该会话；耗尽配额的原因是循环重启服务，而非查询数量。

• 通过虚拟代理进行 JWT 身份验证。 设置 QLIK_JWT_TOKEN，而非证书路径，服务便会以令牌中编码的分析师身份进行每次 Repository 和 Engine 调用。主机上不会保存证书或私钥。旧版证书模式保持不变，且仍是完整访问 QRS 的必要条件。设置指南：docs/AUTH_JWT.md。

• 通过“Form based”虚拟代理进行登录名/密码身份验证。 设置 QLIK_PASSWORD（以及 QLIK_USER_ID，并可选择设置 QLIK_USER_DIRECTORY），而非证书或 JWT。服务会像浏览器一样登录代理的登录页面，然后复用由此获得的会话 Cookie，其方式与 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 的请求，并返回结构化错误以及指向集合分析或 Top-N 模式的提示。对于超过 10000 个单元格的任何单页数据，Qlik Engine 本身都会返回 错误 7009 calc-pages-too-large。

• 两个超时参数。 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