tableau-graphql-mcp

tableau-graphql-mcp

通过 Tableau Metadata API，在任意 MCP 客户端中询问任何 Tableau 血缘问题。

tableau-graphql-mcp 将 Tableau 站点的 Metadata API 转化为一组 MCP 工具，让 AI 助手（Claude、Cursor、Cline 等）能够用通俗语言回答血缘问题：

• “如果我删除 SALES 列，哪些工作簿会出问题？”
• “Sales Overview 工作簿依赖哪些表？”
• “哪些计算字段引用了 Profit，以及它们出现在哪些仪表板上？”
• “更改 DIM_CUSTOMER 表之前，我应该通知谁？”

它提供 七种精选工具：通用 GraphQL 透传、实时模式内省、内置的正确查询模板库、可靠的 where_used 解析器、多跳 impact_analysis、子字符串内容搜索，以及连接探测工具。它们结合起来，能让模型回答任何血缘问题，而不仅仅是固定选项中的问题。

与众不同之处

• 任何问题，都能妥善解决。 graphql_query 可执行任意只读 GraphQL 查询；introspect_schema、内置速查表和 28 个完整示例可确保模型的查询正确无误。
• 真正的影响分析（多跳）。 impact_analysis 会追踪整个依赖链（基于计算字段构建的计算字段，以及基于它构建的列，都会纳入分析），并返回完整的影响范围，以及去重后的待通知负责人，而不只是直接引用项。
• 随处可用。 支持 Tableau Server 和 Cloud。REST API 版本和 GraphQL 端点（/api/metadata/graphql，并以 /relationship-service-war/graphql 作为回退）会自动检测。
• 无需 Catalog，也能可靠追踪数据沿袭。 where_used 通过核心沿袭关系（referencedByFields -> sheets -> workbook）解析工作簿，因此即使 Data Management 附加组件的 downstreamWorkbooks 为空，也能正常工作。
• 不会悄悄截断结果。 如果查询达到节点上限，graphql_query 会标记 partial_results；search_content 会报告 scanned/total 覆盖情况，确保不会把截断后的答案误认为完整结果。
• 轻巧且安全。 只读、仅使用 stdio（不开放入站端口）、密钥仅从环境变量读取，并且除 MCP SDK 外没有其他依赖（HTTP 使用标准库 urllib）。

快速开始

你需要 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）和 Tableau 个人访问令牌。

Claude Code，一行命令：

claude mcp add tableau-graphql \
  -e TABLEAU_SERVER=https://10ax.online.tableau.com \
  -e TABLEAU_SITE_CONTENT_URL=YourSite \
  -e TABLEAU_PAT_NAME=my-token \
  -e TABLEAU_PAT_SECRET=the-full-secret \
  -- uvx tableau-graphql-mcp

就这么简单。uvx 会从 PyPI 获取软件包，并在隔离环境中运行；无需克隆或安装（也不需要 git）。然后向 Claude 提出有关数据沿袭的问题。

配置

所有配置均通过环境变量完成（在客户端的 env 块中设置，切勿在命令行中设置）。

¹ 请提供 PAT（TABLEAU_PAT_NAME + TABLEAU_PAT_SECRET）或高级选项 TABLEAU_AUTH_TOKEN / TABLEAU_COOKIE。

{
  "mcpServers": {
    "tableau-graphql": {
      "command": "uvx",
      "args": ["tableau-graphql-mcp"],
      "env": {
        "TABLEAU_SERVER": "https://10ax.online.tableau.com",
        "TABLEAU_SITE_CONTENT_URL": "YourSite",
        "TABLEAU_PAT_NAME": "my-token",
        "TABLEAU_PAT_SECRET": "the-full-secret"
      }
    }
  }
}

工具

所有工具均为只读。Metadata API 不支持任何变更操作。

示例提示词

连接后，试试：

• "使用 server_info 确认当前连接的对象。"
• "搜索名称中包含 'revenue' 的所有内容。"
• "哪些工作簿使用了 SALES、PROFIT 和 DISCOUNT 列？按所有者分组。"
• "显示 'Sales Overview' 工作簿的字段到源列映射。"
• "列出该工作簿中的所有计算字段及其公式。"
• "哪些已发布数据源为 Analytics 项目中的工作簿提供数据？哪些未经认证？"
• "对 'Profit Ratio' 字段运行 impact_analysis：列出所有依赖的工作表、仪表板、工作簿，以及需要通知的所有者。"
• "删除 DIM_CUSTOMER 表会造成多大影响：涉及哪些工作簿、工作表，以及需要通知的所有者？"

架构

该服务通过 stdio 使用 MCP 与客户端通信，并通过 HTTPS 连接 Tableau：它使用你的 PAT 登录以获取 X-Tableau-Auth 令牌（过期时自动刷新），自动检测 REST API 版本和 GraphQL 端点，然后将查询转发到 Metadata API。不会存储任何内容；每个答案都是实时获取的。

安全性

• 强制只读。 仅允许 GraphQL 查询：不写入、不执行 shell。graphql_query 会拒绝 mutation/subscription 操作，而 Metadata API 本身也只能用于查询。
• 声明为只读。 每个工具都带有 MCP readOnlyHint 注解，客户端无需阅读代码即可验证。
• 仅限本地和 stdio。 不会开放任何入站网络端口。
• 密钥仅从环境变量读取。 绝不会作为工具参数传入，不会记录日志，也不会在输出中返回。
• 凭据仅发送到你的 Tableau 主机。 必须使用 HTTPS、验证证书，并拒绝重定向。
• 最小权限。 PAT 继承你的 Tableau 权限；API 只会返回你有权查看的内容。
• 可验证的发布版本。 每个 GitHub 发布版本都附带 Sigstore 签名和 CycloneDX SBOM，PyPI 上传则使用 Trusted Publishing。
• 在生产环境中固定版本：uvx tableau-graphql-mcp==0.2.0。

有关威胁模型、数据处理、披露政策以及如何验证发布版本，请参阅 SECURITY.md。

故障排除

使用 MCP Inspector 直接检查服务：

npx @modelcontextprotocol/inspector uvx tableau-graphql-mcp

开发

git clone https://github.com/tdries/tableau-graphQL-mcp && cd tableau-graphQL-mcp
uv sync --all-extras
uv run tableau-graphql-mcp                     # run from source
uv run pytest --cov=tableau_graphql_mcp        # tests + coverage (offline; no Tableau needed)
uv run ruff check .                            # lint
uv run ruff format --check .                   # format

CI 中会运行相同的检查（Linux/macOS/Windows，Python 3.10 到 3.13）：ruff check、 ruff format --check、mypy --strict，以及设有覆盖率下限的 pytest。该软件包 附带 PEP 561 py.typed 标记，因此导入后，类型检查器即可获得完整类型信息。 CodeQL 会扫描每次推送；每周运行的模糊测试任务（fuzz/）会针对只读保护机制进行攻击测试。

欢迎贡献：请参阅 CONTRIBUTING.md 和行为准则。

路线图

已完成：已发布到 PyPI，并列入官方 MCP 注册表。接下来：

• 可选的 Data Management 路径：存在 Catalog 时提供更丰富的 downstreamWorkbooks 信息
• 在 lineage_examples 中添加更多精选查询模板
• 可选的响应缓存，用于缓存会话内重复的内省查询

欢迎在 讨论区分享想法和投票。

License

MIT © Tim Dries. Built at Biztory.