sisense-mcp-server

Sisense MCP 服务

警告

已弃用。 此存储库已停止维护，即将归档。 Sisense MCP 服务现已作为托管端点提供，并支持 OAuth 2.1，可在 Sisense 2026.3.1 中使用。 请参阅 Sisense MCP 服务文档了解设置方法。 此存储库不会再获得新功能或修复。

一个可与 Sisense 分析平台集成的模型上下文协议（MCP）服务。此服务可让大模型与 Sisense 数据模型交互，并以编程方式创建图表。

功能

• 传输方式：Streamable HTTP（streamable-http），适用于基于 HTTP 的 MCP 客户端（例如 Claude Desktop、Cursor）
• MCP 工具（默认提供三个；启用后可提供第四个）：
  • getDataSources：获取 Sisense 数据源（或数据模型）
  • getDataSourceFields：列出特定数据源的所有可用字段
  • buildChart：根据自然语言提示词构建图表
  • buildQuery（可选）：启用 TOOL_BUILD_QUERY_ENABLED / toolBuildQueryEnabled 后运行分析查询
• MCP Apps：在支持 MCP Apps 的客户端（例如 Claude）中使用时，buildChart 会提供交互式视图，可在应用内的 iframe 中呈现图表。
• 每个会话单独认证：通过 URL 参数和/或服务环境变量提供 Sisense 凭据
• TypeScript：提供完整的类型安全和现代 ESM 支持
• 轻量：纯 Node.js HTTP 服务，不依赖重量级框架
• 快速：针对 Bun 运行时优化，也可在 Node.js 上运行

文档

• 快速入门 — 克隆、配置 .env、运行及 MCP 客户端设置
• 配置 — 凭据、隧道、功能标志、URL 示例
• 常见问题 — 常见问题与故障排查
• 使用示例 — 提示词和工作流

前提条件

• Node.js >= 18.0.0（本地开发和 npm 所需）
• Bun 用于运行项目脚本（dev、build、start、测试）：bun 包是一个 devDependency，因此执行 npm install 或 bun install 后，Bun 二进制文件会位于 node_modules/.bin 中——无需全局安装 Bun。全局安装 Bun 是可选的。
• 可通过 API 访问的 Sisense 实例
• Sisense API 令牌
• 在 Sisense 实例上启用 Cloud-Linked Features（如果使用自带密钥（BYOK），还需配置 LLM 提供商）。自然语言工具（如 buildChart 和 buildQuery）需要此功能。请参阅 生成式 AI（Cloud-Linked Features）。这与 MCP 客户端使用的大模型（例如 Cursor 中的 Claude）是分开的。
• Playwright Chromium（通过 postinstall 在 bun install / npm install 时自动安装）

安装

bun install
# or
npm install

用法

启动服务：

# Development mode (hot reload)
bun run dev
# or
npm run dev

# Production mode
bun run build && bun run start
# or
npm run build && npm run start

会话数据保存在内存中——如果服务重启，图表状态将丢失。

服务会输出类似以下内容（默认端口为 3001，如果设置了 PORT，则使用该值）：

Sisense MCP Server running on http://localhost:3001

Connect with:
  http://localhost:3001/mcp?sisenseUrl=<SISENSE_URL>&sisenseToken=<SISENSE_TOKEN>
  Or set SISENSE_URL and SISENSE_TOKEN in the environment and use http://localhost:3001/mcp

Optional feature-flag query params (override env vars per connection):
  mcpAppEnabled=true|false, toolBuildQueryEnabled=true|false, toolBuildChartNarrativeEnabled=true|false

Endpoints:
  Health: http://localhost:3001/health
  Screenshots: http://localhost:3001/screenshots/

连接 MCP 客户端

使用 MCP 可流式传输的 HTTP URL。对于 Cursor、Claude Desktop 等客户端，请添加包含 MCP 路径的服务条目（而不是 bun run dev 或 npm run dev 这样的 shell 命令）。

如果在服务端环境中设置了 SISENSE_URL 和 SISENSE_TOKEN（例如，在运行 bun run dev 或 npm run dev 的进程加载的 .env 文件中设置），则客户端 URL 无需包含凭据：

{
  "mcpServers": {
    "sisense-analytics": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

**注意：**根据网络或客户端环境，localhost HTTP 设置可能无法连接。在这种情况下，你需要使用 ngrok 等代理服务，通过 HTTPS 将本地服务公开。将客户端指向 HTTPS 隧道 URL，并使用相同的 /mcp 路径（如果未使用服务端环境凭据，还需添加查询参数）。

**凭据：**如果不使用服务端环境变量，请将 sisenseUrl 和 sisenseToken 作为查询参数添加到 MCP URL 中（同时存在时，URL 参数优先于环境变量）。务必对每个值进行百分号编码——详情和示例请参阅配置：URL 编码。

其他连接方式（仅为占位示例；实际凭据请使用编码后的值）：

http://localhost:3001/mcp?sisenseUrl=https://your-instance.sisense.com&sisenseToken=your-api-token

仅在服务端环境中设置 SISENSE_URL 和 SISENSE_TOKEN：

http://localhost:3001/mcp

使用公开 HTTPS 隧道（示例）：

https://your-ngrok-url.ngrok-free.app/mcp?sisenseUrl=https://your-instance.sisense.com&sisenseToken=your-api-token

Claude（claude.ai 和 Desktop）：交互式图表的 Sisense CORS 设置

在 MCP App 模式（默认模式）下，Anthropic Claude 会在 MCP 内容 UI 中渲染图表——无论是在 claude.ai 还是 Claude Desktop 中。浏览器会从 *.claudemcpcontent.com 下的来源加载你的 Sisense 实例，因此 Sisense 必须允许这些来源，否则小组件会因网络或 CORS 错误而无法正常工作。

在 Sisense 实例中，前往 管理 → 安全设置 → CORS 允许的来源，并添加：

https://*.claudemcpcontent.com

请使用这种子域名通配符形式。单个来源（如 https://claudemcpcontent.com，没有 *.）可能无法匹配实际的框架来源，导致图表仍无法加载。

更多背景信息：常见问题：Claude MCP App 图表与 CORS。

配置

参数	描述
sisenseUrl	Sisense 实例的完整 URL（例如，https://instance.sisense.com）。在查询字符串中传递该值时，请进行百分号编码。
sisenseToken	Sisense API 身份验证令牌。在查询字符串中传递该值时，请进行百分号编码（如果令牌包含 &、=、+ 等字符，则必须编码）。
PORT	（可选）服务端口，默认为 3001

服务会根据请求标头自动推导其公开的基础 URL，因此可在 ngrok 等代理后正常工作。有关如何构建编码后的 MCP URL，请参阅查询参数的 URL 编码。

可选的功能标志查询参数

默认设置适用于大多数场景；需要特定的客户端行为时，请更改标志。如需了解各标志的适用场景、可直接复制粘贴的 URL 格式，以及环境变量与查询字符串的区别，请参阅 docs/guides/configuration.md。

这些查询参数会针对每个连接覆盖相应的环境变量。可接受的值：true、false、1、0（不区分大小写）。

查询参数	对应的环境变量	默认值	描述
mcpAppEnabled	MCP_APP_ENABLED	true	在交互式应用 UI 中呈现图表（Claude 支持）；设为 false 可使用工具模式（输出图像/屏幕截图）
toolBuildQueryEnabled	TOOL_BUILD_QUERY_ENABLED	false	启用用于执行分析查询的 buildQuery 工具
toolBuildChartNarrativeEnabled	TOOL_BUILD_CHART_NARRATIVE_ENABLED	true	在构建图表工具的响应中加入自然语言生成（NLG）叙述/洞察

包含全部三个覆盖项的示例 URL（sisenseUrl 和 sisenseToken 的值不是简单的字母数字占位符时，请对其进行编码）：

http://localhost:3001/mcp?sisenseUrl=https://your-instance.sisense.com&sisenseToken=your-api-token&mcpAppEnabled=false&toolBuildQueryEnabled=true&toolBuildChartNarrativeEnabled=false

开发

# Run server in development mode with hot reload
bun run dev
# or npm run dev

# Build the project (View + server)
bun run build
# or npm run build

# Build only the analytics View (dist/view.html)
bun run build:view
# or npm run build:view

# Run tests
bun test
# or npm test (same as npm run test)

# Type checking
bun run type-check
# or npm run type-check

# Lint
bun run lint
# or npm run lint

安全注意事项

⚠️ 切勿将凭据提交到版本控制中

⚠️ 使用密钥管理器或保管库——生产环境中不要使用环境变量

⚠️ 生产环境中切勿绑定到 0.0.0.0——请使用 127.0.0.1 或 Unix 套接字

⚠️ 建议：如果有开发或预发布环境，请使用 Sisense 的开发或预发布环境。自主 AI 客户端可能会发起大量 API 调用，而提示词也可能含糊不清。使用非生产环境可降低错误和意外情况的影响。

⚠️ 启用身份验证——切勿在未启用身份验证的情况下运行

⚠️ 审批每一次工具调用——执行前检查所有参数

⚠️ 创建专用的 Sisense 服务账户，并仅授予所需的最低权限

⚠️ 定期轮换凭据（建议每 90 天轮换一次）