@guandata/guanbi-mcp-server

v0.1.27

Published

4 days ago

MCP server for exposing GuanBI capabilities to AI agents.

0High
0Medium
0Low

guanbi guandata mcp mcp-server bi business-intelligence chatbi ai-agent

@guandata/guanbi-mcp-server

观远 BI MCP Server，用于把 BI 的检索、元信息读取、能力探测、SQL 查询、指标平台、指标树和 ChatBI 能力暴露给支持 MCP 的 Agent。

MCP 配置

使用 npm package：

{
  "mcpServers": {
    "guanbi": {
      "command": "npx",
      "args": ["-y", "@guandata/guanbi-mcp-server@latest"],
      "env": {
        "BI_BASE_URL": "http://guandata-web:8088",
        "BI_UID_TOKEN": "your-token"
      }
    }
  }
}

配置项

配置项可以通过 MCP 客户端的 env 字段传入。

通用配置

| 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | BI_BASE_URL | 否 | http://guandata-web:8088 | BI 站点根地址；默认指向 Kubernetes 集群内的 guandata-web 服务，非该部署场景请显式覆盖。 | | BI_PUBLIC_PATH | 否 | 空字符串 | BI 部署在子路径时填写，例如 /guanbi。 | | BI_PAT_CLIENT | 否 | mcp | 仅 PAT 调普通 BI 接口时发送为 X-Guandata-Client；为空或空字符串时使用 mcp。HTTP PAT 模式可由请求头 X-Guandata-Client 覆盖。 | | BI_REQUEST_TIMEOUT_MS | 否 | 120000 | BI 请求超时时间，单位毫秒。 | | BI_MAX_ROWS | 否 | 1000 | execute_sql_query 返回行数上限，会作为 limit 参数传给 BI 接口；实际限制以 BI 接口能力为准。 | | BI_DATA_VERSION | 否 | - | 手工覆盖能力判断使用的 BI 版本，例如 8.2.0。 | | GUANBI_MCP_USAGE_STATS | 否 | 开启 | 匿名聚合使用统计开关；设置为 0、false、off 或 no 可关闭。 | | MCP_TRANSPORT | 否 | stdio | 运行模式；传 streamable-http 启用企业 HTTP 模式。 |

仅 PAT 调普通 BI 接口时会发送 X-Guandata-Client，默认值为 mcp；stdio 可用 BI_PAT_CLIENT 覆盖，HTTP PAT 可用请求头 X-Guandata-Client 覆盖。非 PAT 鉴权不发送该 Header。

stdio 配置

| 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | BI_PAT | 否 | - | 本地 GuanBI Personal Access Token；仅用于 stdio 模式，优先于 BI_UID_TOKEN 和账号密码登录。 | | BI_UID_TOKEN | 否 | - | 本地固定调用者登录态 token；未配置 BI_PAT 时优先使用。 | | BI_LOGIN_DOMAIN | 否 | guanbi | 账号密码登录使用的 domain。 | | BI_LOGIN_ID | 否 | - | 登录账号。 | | BI_LOGIN_PASSWORD | 否 | - | 登录密码。 |

stdio 模式访问 BI 需要满足以下任一条件：

配置 BI_PAT。
配置 BI_UID_TOKEN。
同时配置 BI_LOGIN_DOMAIN、BI_LOGIN_ID、BI_LOGIN_PASSWORD。

HTTP 配置

| 变量 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | MCP_HTTP_HOST | 否 | 127.0.0.1 | HTTP 监听地址。 | | MCP_HTTP_PORT | 否 | 9090 | HTTP 监听端口。 | | MCP_ENTRYPOINT_TOKEN | Aily / identity exchange 模式必填，除非启用可信网关 | - | MCP HTTP 入口 bearer token；PAT 请求可只携带 X-Personal-Token。 | | MCP_TRUSTED_GATEWAY | 否 | - | 设为 true 时跳过 MCP 入口 token 校验，仅用于可信网关已完成鉴权的部署。 | | BI_APP_TOKEN | identity exchange 模式必填 | - | Public API 应用 Token；必须保存在 MCP 服务端 Secret 中。请求中不能携带 app token。 | | BI_LOGIN_ID_HEADER | 否 | x-guanbi-login-id | 读取 GuanBI loginId 的请求 header 名；设为空字符串可禁用直接 loginId 路径。 | | BI_USER_PROPERTY_HEADER | 否 | - | 读取外部用户属性值的请求 header 名，例如 x-aily-user。 | | BI_USER_PROPERTY_KEY | 使用 BI_USER_PROPERTY_HEADER 时必填 | - | BI_USER_PROPERTY_HEADER 对应的 BI 用户属性 key，例如 feishu。 | | BI_IDENTITY_DEBUG | 否 | - | 设为 true 时，identity exchange 失败会在错误响应和 stderr 日志中输出脱敏 debug 信息；仅建议排查时临时开启。 | | BI_IDENTITY_TOKEN_CACHE_TTL_MS | 否 | 600000 | identity exchange 换出的用户 token 进程内短缓存时间。 |

HTTP 模式不使用服务端环境变量 BI_PAT 作为全局 BI 身份。个人 PAT 需要由请求 header X-Personal-Token 传入；该请求不需要 Authorization，PAT 优先于请求 token、loginId 和用户属性 identity exchange。未传 PAT 时，HTTP 不使用账号密码登录，也不使用进程级 BI_UID_TOKEN 给所有用户代查。HTTP 下有两类用户登录方式： PAT 模式仅支持普通 BI 接口，不注册 ChatBI tools。

请求直传 BI uIdToken：调用方或网关已经拿到当前用户的 GuanBI uIdToken，每次请求带 X-GuanBI-Uid-Token。这种方式不需要 BI_APP_TOKEN，优先级最高。
服务端 identity exchange：调用方拿不到 uIdToken，但能提供可信的 GuanBI loginId，或能映射到 BI 用户属性的外部用户 id。MCP 服务端配置 BI_APP_TOKEN 后，使用 BI_LOGIN_ID_HEADER 或 BI_USER_PROPERTY_HEADER + BI_USER_PROPERTY_KEY 换出当前用户 uIdToken。

请求传 X-Personal-Token 时，PAT 优先于上述请求身份。

HTTP 模式

本地 MCP 客户端使用建议保留默认 stdio 模式。如果需要把 MCP server 作为常驻 HTTP 服务部署，可以启用 streamable-http：

MCP_TRANSPORT=streamable-http \
MCP_HTTP_HOST=127.0.0.1 \
MCP_HTTP_PORT=9090 \
MCP_ENTRYPOINT_TOKEN=change-me \
BI_BASE_URL=http://guandata-web:8088 \
npx -y @guandata/guanbi-mcp-server@latest

HTTP 入口使用 POST /mcp。Aily / identity exchange 链路需要携带 Authorization: Bearer <mcp_service_token>，除非设置 MCP_TRUSTED_GATEWAY=true 并由可信网关完成鉴权；个人 PAT 链路可只携带 X-Personal-Token。

个人 PAT 请求示例：

X-Personal-Token: <personal-access-token>
# Optional, defaults to mcp.
X-Guandata-Client: cli

请求直传 token 模式需要带：

X-GuanBI-Uid-Token: <uIdToken>

identity exchange 模式需要服务端配置 BI_APP_TOKEN，请求侧二选一：

X-GuanBI-Login-Id: <loginId>
<BI_USER_PROPERTY_HEADER>: <external user id>

Aily / 飞书接入默认可以用 x-aily-user 映射 BI 用户属性 feishu。如果飞书 user id（Aily 中询问得到的用户 id）和飞书管理后台「成员与部门」->「成员详情」->「用户ID」中看到的用户 ID 不同，可以改用邮箱匹配：

BI_USER_PROPERTY_HEADER=x-aily-email
BI_USER_PROPERTY_KEY=email

邮箱匹配要求飞书里每个用户都配置了邮箱，且邮箱已同步到 BI 用户属性 email 中，并能唯一匹配一个 BI 用户。

X-GuanBI-Login-Id、BI_USER_PROPERTY_HEADER 配置的用户属性 header 等身份 header 是普通 HTTP header，必须只来自可信调用方或网关确认后的身份映射。可信网关模式下，网关必须覆盖注入身份 header，不能透传外部请求自带的同名 header。

Tools

get_bi_capabilities：获取 BI 版本和当前 MCP 可用能力。
global_search：搜索卡片、仪表板、数据集、ETL。
execute_sql_query：在支持的环境中执行单条只读 SQL 查询；建议先用 get_dataset_detail 确认数据集名称和字段名。inputs 只传对应数据集 ID，SQL 通常先用数据集名称作为表引用；若返回表名错误，按 diagnostic.tableBindings 提供的执行链路引用修正。支持无表查询和兼容的多数据集查询。
get_dataset_detail：获取数据集详情。
get_card_info：获取卡片元信息。
query_card_data：只读查询图表卡、筛选器、树筛选器和文本卡片数据，支持结构化 filters、columns 投影和 raw 诊断。
get_page_info：获取页面或仪表板元信息。
search_metrics、list_metric_catalog、get_metric_detail、query_metric_data：发现并查询指标平台指标。
search_metric_trees、get_metric_tree_detail、query_metric_tree_attribution：发现指标树并执行归因分析。
chatbi_list_themes、chatbi_query、chatbi_insight_start、chatbi_insight_poll：使用 ChatBI 主题、同步问数和异步洞察分析。

说明

服务默认只发送匿名、聚合的使用统计事件。不会采集 SQL、自然语言问题、tool 参数、token、cookie、完整 URL、资源 ID、返回内容、用户 ID、账号或长期客户端标识。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@guandata/guanbi-mcp-server

MCP 配置

配置项

通用配置

stdio 配置

HTTP 配置

HTTP 模式

Tools

说明