Tableau Workbook MCP

Tableau工作簿MCP服务器

一个MCP（模型上下文协议）服务器，通过REST API下载Tableau工作簿，并提取其XML内容供Claude解释。

概述

此MCP服务器使Claude能够通过以下方式分析Tableau工作簿：

• 使用REST API从Tableau服务器或Tableau云下载工作簿
• 从.twb和.twbx格式中提取XML结构
• 解析连接、仪表板和工作表信息
• 以LLM优化格式呈现工作簿结构

特性

• 无缝集成：与现有的Tableau MCP服务器协同工作
• 安全认证：使用个人访问令牌（PAT）进行身份验证
• 灵活解析：连接和仪表板的可选解析
• 性能优化：默认情况下不包括摘要，以实现更快的下载
• 差错恢复：全面的错误处理，并提供可操作的建议
• 上下文感知：自动截断XML以遵守LLM上下文窗口

先决条件

在使用此MCP服务器之前，请确保您已：

1. Node.js：18.0.0或更高版本
2. Tableau访问：访问Tableau服务器或Tableau云
3. 个人访问令牌：创建具有适当权限的PAT
4. 现有Tableau MCP：用于查找工作簿ID的Tableau MCP官方服务器

安装

1.安装依赖项

导航到项目目录并安装Node.js依赖项：

cd /Users/qchriste/Library/CloudStorage/OneDrive-CHGHealthcare/Documents/Development/tableau-workbook-mcp
npm install

2.建设项目

将TypeScript编译为JavaScript：

npm run build

这将在 dist/ 目录。

3.验证安装

检查服务器是否可以启动：

node dist/index.js --help

配置

环境变量

此MCP服务器需要与现有Tableau MCP分开配置。将以下环境变量添加到MCP客户端配置中：

• TWB服务器：您的Tableau服务器URL（例如。， https://tableau.example.com)
• TWB_SITE_NAME：您的Tableau站点名称（使用空字符串 "" 默认站点）
• TWB_PAT_NAME：您的个人访问令牌名称
• TWB_PAT_TOKEN：您的个人访问令牌密钥

Claude桌面配置

将此服务器添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "tableau": {
      "command": "npx",
      "args": ["-y", "@tableau/mcp-server@latest"],
      "env": {
        "SERVER": "https://my-tableau-server.com",
        "SITE_NAME": "my_site",
        "PAT_NAME": "my_pat",
        "PAT_VALUE": "pat_value"
      }
    },
    "tableau-workbook": {
      "command": "node",
      "args": [
        "/Users/qchriste/Library/CloudStorage/OneDrive-CHGHealthcare/Documents/Development/tableau-workbook-mcp/dist/index.js"
      ],
      "env": {
        "TWB_SERVER": "https://my-tableau-server.com",
        "TWB_SITE_NAME": "my_site",
        "TWB_PAT_NAME": "my_pat_for_downloads",
        "TWB_PAT_TOKEN": "my_pat_secret_for_downloads"
      }
    }
  }
}

创建个人访问令牌

1. 登录您的Tableau服务器或Tableau云
2. 导航至 我的帐户设置
3. 点击 个人访问令牌 标签
4. 点击 创建新令牌
5. 输入令牌名称并单击 创建
6. 复制 令牌名称 和 令牌密钥 立即（秘密只显示一次）

必需的权限

个人访问令牌必须与具有以下特征的用户帐户相关联：

• 阅读（查看） 您要下载的工作簿的权限
• 导出Xml 对这些工作簿的权限
• 访问特定的Tableau网站

用法

典型工作流程

1. 查找工作簿 使用现有的Tableau MCP：

   Use tableau:list-workbooks to find workbooks named "Sales Dashboard"

1. 下载并分析 使用此MCP：

   Use download_tableau_workbook with the workbook ID from step 1

工具：下载_表格_工作簿

下载Tableau工作簿并提取其XML结构。

参数

示例：基本下载

{
  "workbook_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
}

示例：下载并解压

{
  "workbook_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "include_extract": true
}

示例：无解析下载

{
  "workbook_id": "1a2b3c4d-5e6f-7a8b-9c0d-1e2f3a4b5c6d",
  "parse_connections": false,
  "parse_dashboards": false
}

响应结构

该工具返回一个JSON对象，其中包含：

{
  "workbookId": "string",        // The workbook ID
  "workbookName": "string",      // Filename of the workbook
  "fileType": "twb" | "twbx",   // File format
  "xmlContent": "string",        // Complete XML content
  "structure": {                 // Parsed structure (if enabled)
    "workbookName": "string",
    "connections": [...],        // Connection details
    "dashboards": [...],         // Dashboard structure
    "worksheets": [...],         // Worksheet names
    "dataSourceCount": number,
    "hasParameters": boolean
  },
  "message": "string"            // Status message
}

错误处理

服务器提供详细的、可操作的错误消息：

身份验证错误（401）

Error: Authentication failed (401 Unauthorized)
Suggestion: Verify that your TWB_PAT_NAME and TWB_PAT_TOKEN environment variables are correct...

权限错误（403）

Error: Access forbidden (403 Forbidden)
Suggestion: Verify that your Tableau user account has ExportXml permission...

未找到错误（404）

Error: Workbook not found (404 Not Found)
Suggestion: Verify that the workbook ID is correct. Use tableau:list-workbooks to find the correct ID...

速率限制错误（429）

Error: Rate limit exceeded (429 Too Many Requests)
Suggestion: Wait a few minutes before retrying the request.

发展

项目结构

tableau-workbook-mcp/
├── package.json           # Node.js dependencies and scripts
├── tsconfig.json          # TypeScript compiler configuration
├── README.md              # This file
├── src/
│   ├── index.ts          # Main server entry point
│   ├── types.ts          # TypeScript type definitions
│   ├── constants.ts      # Shared constants
│   ├── schemas.ts        # Zod validation schemas
│   ├── services/
│   │   └── tableauApi.ts # Tableau REST API client
│   └── utils/
│       └── xmlExtractor.ts # XML extraction and parsing utilities
└── dist/                 # Compiled JavaScript (created by build)

构建命令

• 构建: npm run build -将TypeScript编译为JavaScript
• 手表: npm run watch -文件更改时自动编译
• 开始: npm start -运行已编译的服务器
• 开发: npm run dev -自动重启的观看模式

测试

要手动测试服务器，请执行以下操作：

1. 验证编译:

   npm run build

1. 检查环境变量 在MCP客户端配置中设置

1. 使用Claude Desktop进行测试 或通过调用该工具调用另一个MCP客户端

性能注意事项

• 提取大小：设置 include_extract: false （默认）用于更快地下载具有大摘要的工作簿
• XML截断：XML内容会自动截断为25000个字符，以适应Claude的上下文窗口
• 解析开销：禁用 parse_connections 和 parse_dashboards 如果您只需要原始XML
• 下载超时：对于非常大的工作簿，请求在5分钟后超时

故障排除

服务器无法启动

问题：缺少环境变量时出错

解决方案：确保在MCP客户端中配置了TWB_SERVER、TWB_SITE_NAME、TWB_PAT_NAME和TWB_PAT_TOKEN

______________________________________________________________________

问题：TypeScript编译错误

解决方案：运行 npm install 为了确保所有依赖项都已安装，那么 npm run build

身份验证问题

问题：401未经授权的错误

解决方案:

1. 验证您的PAT凭据是否正确
2. 检查令牌是否未过期
3. 确保PAT适用于正确的Tableau站点

下载失败

问题：403禁止错误

解决方案：请与Tableau管理员联系以授予ExportXml权限

______________________________________________________________________

问题：404未找到错误

解决方案：使用现有的Tableau MCP tableau:list-workbooks 查找正确工作簿ID的工具

大型工作簿

问题：超时错误或下载速度非常慢

解决方案:

1. 集 include_extract: false 跳过数据提取
2. 增加 REQUEST_TIMEOUT 在 src/constants.ts 如有需要

安全说明

• 个人访问令牌存储在环境变量中（而不是代码中）
• 令牌通过HTTPS传输到Tableau服务器
• 每次请求后，身份验证令牌都会失效
• 没有记录凭据或将凭据写入磁盘

与现有Tableau MCP集成

此服务器旨在补充官方Tableau MCP服务器：

局限性

• 最大下载大小：64MB（Tableau REST API限制）
• XML截断：Claude的内容限制为25000个字符
• 单个工作簿：一次下载一个工作簿
• 只读：无法修改或上传工作簿

许可证

麻省理工学院

支持

关于以下问题：

• 此MCP服务器：在此存储库中提交问题
• Tableau REST API：咨询 Tableau REST API文档
• MCP协议：参观 模型上下文协议文档

版本历史

1.0.0（初始版本）

• 通过REST API下载Tableau工作簿
• 从.twb和.twbx格式提取XML
• 解析连接和仪表板结构
• 上下文窗口的自动XML截断
• 具有可操作消息的全面错误处理