mcp-tableau
The mcp-tableau server enables AI agents to automate the discover → build → validate → publish lifecycle for Tableau Server/Cloud content. It exposes the following capabilities:
Deploy & Publish
publish_workbook— Publish or overwrite workbooks (.twb/.twbx) to a Tableau project; supports chunked upload for large files.publish_datasource— Publish or overwrite datasources (.tds/.tdsx/.hyper) to a Tableau project.
Visual Inspection
render_view_image— Render a view as a PNG image with optional filters; includes blank-screen heuristic detection.render_workbook_pdf— Render a view as a PDF (configurable page format) with optional filters.
Structural QA & Audit
inspect_workbook_structure— Parse a published workbook to report worksheets, dashboards, connections, fields, filters, and detected issues (broken fields, invalid connections, etc.).audit_workbook_complexity— Audit complexity metrics (worksheet count, filter count, data sources) against best-practice thresholds, flagging performance risks.
Metadata & Lineage
get_downstream_lineage— Discover all workbooks that depend on a given datasource.get_upstream_lineage— Discover all datasources a workbook depends on.get_datasource_dictionary— Retrieve a field dictionary for a datasource (name, datatype, formula, description).search_similar_content— Fuzzy-search workbooks and/or datasources by name to detect duplicates before publishing.
Local Hyper Extract Management
Create
.hyperfiles from CSV, Parquet, inline data, or external databases.Inspect schema (schemas, tables, columns, row counts) of
.hyperfiles.Query data (read-only
SELECT/WITH) from.hyperfiles.Append data from files or inline sources to existing
.hypertables.Execute modification commands (
INSERT/UPDATE/DELETE/CREATE TABLE AS) on.hyperfiles.Publish
.hyperextracts as Tableau datasources, closing the local-to-cloud pipeline.
Allows extracting data from MySQL databases into Tableau Hyper extracts for subsequent publication as Tableau datasources.
Allows extracting data from PostgreSQL databases into Tableau Hyper extracts for subsequent publication as Tableau datasources.
Allows extracting data from SQLite databases into Tableau Hyper extracts for subsequent publication as Tableau datasources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-tableau publish the sales dashboard to Tableau Server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP Tableau
Servidor Model Context Protocol construído com FastMCP que expõe ferramentas para automatizar o ciclo de publicação e validação de conteúdo no Tableau Server / Tableau Cloud.
O objetivo é permitir que um agente de IA autônomo complete o fluxo descobrir → construir → validar → publicar sem intervenção humana, com retornos estruturados e auditáveis. As capacidades cobrem:
Deploy — publicar/sobrescrever workbooks (
.twb/.twbx) e datasources (.tds/.tdsx/.hyper).Inspeção visual — renderizar PNG/PDF de views e sinalizar telas em branco.
QA estrutural — ler campos, filtros e conexões; auditar complexidade contra boas práticas.
Metadados — linhagem ascendente/descendente, dicionário de dados e busca de similaridade.
Hyper Datasources — criar, consultar, inspecionar e transformar extratos
.hyperlocais (de CSV/Parquet, dados inline ou bancos externos) antes de publicar.
🚀 Começando agora? Veja o QUICKSTART para rodar o servidor via
uvxe configurar nos principais agentes (Claude, GitHub Copilot, Cursor, Kiro e outros).
Stack
Linguagem: Python
>= 3.13Framework MCP: FastMCP (
>= 3.4.2), transporte stdioIntegração Tableau:
tableauserverclient(REST API) + Metadata API (GraphQL)Extratos Hyper:
tableauhyperapi(runtime local.hyper) +sqlalchemy(extração de bancos externos)Parsing/validação:
tableaudocumentapi,Pillow,rapidfuzz,pydanticGerenciador de pacotes: uv
⚠️ O
tableauhyperapiembarca um runtime binário (~150 MB) e só roda em plataformas x64/arm64 de Linux, macOS e Windows. Ver QUICKSTART.
Related MCP server: Tableau MCP Server
Instalação
Requer uv e Python >= 3.13.
uv syncConfiguração
As credenciais são lidas de variáveis de ambiente (autenticação via Personal Access Token). Copie o exemplo e preencha os valores:
cp .env.example .envVariável | Obrigatória | Default | Descrição |
| sim | — | URL do Tableau Server/Cloud. |
| sim | — | Nome do Personal Access Token. |
| sim | — | Segredo do PAT (nunca é logado nem retornado). |
| não |
| Content URL do site (vazio = site default no Server). |
| não |
| Tempo limite das requisições à API, em segundos. |
| não |
| Limiar de filtros para auditoria de complexidade. |
| não |
| Limiar de worksheets. |
| não |
| Limiar de fontes de dados. |
| não |
| Limiar de tamanho (MB) do arquivo de origem em |
| não |
| Limiar de linhas inline em |
| não |
| Default de linhas retornadas por |
| não |
| Limiar de linhas extraídas em |
| não | — | Connection string SQLAlchemy de uma conexão nomeada (ver Capacidade 5). |
O arquivo
.envé ignorado pelo Git. Nunca commite credenciais.Os limiares
HYPER_*geram alertas não bloqueantes (nunca bloqueio): ao exceder um limiar, a tool retorna umVolumeAlerte a operação só prossegue comconfirm_large_operation=true.
Execução
Inicia o servidor MCP em transporte stdio:
uv run python main.pyCapacidade 5 — Hyper Datasources
Ferramentas para o ciclo de vida local de extratos .hyper antes da
publicação. Todas operam sobre caminhos locais informados pelo agente e delegam ao
runtime tableauhyperapi (iniciado sob demanda, sem processo residente).
Ferramenta | O que faz |
| Cria um |
| Cria um |
| Extrai o resultado de uma query de um banco externo (via conexão nomeada) para um |
| Lista schemas, tabelas, colunas e contagem de linhas de um |
| Executa uma consulta de leitura ( |
| Acrescenta dados (de arquivo ou inline) a uma tabela existente, validando o schema antes de gravar. |
| Executa um comando de modificação ( |
O .hyper gerado é publicado como datasource com publish_datasource (aceita
.tds/.tdsx/.hyper), fechando o fluxo CSV/banco → .hyper → datasource.
Conexões de banco externo (nomeadas)
extract_database_to_hyper recebe apenas o nome lógico da conexão — a
connection string vem da variável de ambiente HYPER_DB_CONN_<NOME> (com <NOME>
em maiúsculas) no host do servidor MCP. Credenciais nunca são parâmetro das
tools, nem aparecem em logs, erros ou retornos.
# A tool chamada com connection_name="VENDAS" lê esta variável:
HYPER_DB_CONN_VENDAS=postgresql+psycopg://usuario:senha@host:5432/baseDrivers de banco não são dependência do projeto — apenas o SQLAlchemy Core é instalado. O administrador instala no host o driver correspondente a cada fonte, conforme a connection string usada:
Fonte | Driver (exemplo) | Connection string |
PostgreSQL |
|
|
SQL Server |
|
|
Oracle |
|
|
MySQL |
|
|
SQLite | (embutido) |
|
Ciclo de vida e limpeza dos .hyper
O agente informa caminhos absolutos de leitura e escrita — não há workspace
sandbox. A localização e a limpeza dos .hyper intermediários são
responsabilidade do operador. Recomendações:
Use um diretório dedicado para os extratos (ex.:
/data/extratos/), fora de áreas versionadas ou sincronizadas.Remova os
.hyperintermediários após a publicação — são reprodutíveis a partir da origem e podem ocupar bastante espaço.Trate o conteúdo dos extratos como dado sensível: aplique as mesmas políticas de acesso/retenção da fonte original.
Estrutura do projeto
mcp-tableau/
├── src/mcp_tableau/
│ ├── __init__.py # versão do pacote
│ ├── server.py # instância FastMCP + registro das tools (stdio)
│ ├── config.py # Settings (env) e carregamento validado
│ ├── models.py # contratos Pydantic de saída + envelope ToolError
│ ├── tableau/ # integração REST (client.py) e GraphQL (metadata.py)
│ ├── tools/ # ferramentas MCP por capacidade
│ └── validation/ # regras de validação puras (sem rede)
├── tests/ # testes espelhando src/ (pytest)
├── main.py # ponto de entrada (inicia o servidor)
└── pyproject.toml # dependências e configuração de ferramentasTestes
A suite rápida (unitários + integração MCP in-memory) mocka toda a rede/Tableau:
uv run pytest # suite rápida + cobertura
uv run pytest -m integration # integração com Tableau realA suite rápida exclui a integração real e aplica o gate de cobertura ≥ 80%
(--cov-fail-under=80) automaticamente — ambos configurados em addopts no
pyproject.toml. A integração com Tableau real (publish/download roundtrip, render PNG e
linhagem) é marcada com @pytest.mark.integration, fica fora da suite rápida e só roda
com TABLEAU_INTEGRATION=1 e as variáveis de sandbox definidas
(TABLEAU_IT_WORKBOOK_PATH, TABLEAU_IT_PROJECT, TABLEAU_IT_VIEW_ID,
TABLEAU_IT_DATASOURCE_ID); caso contrário, esses testes são pulados.
Os testes de integração do Hyper (tests/integration/test_hyper_real.py) usam o
runtime real do tableauhyperapi e rodam offline (sem Tableau): pulam apenas
se o runtime não estiver instalado. A exceção é a publicação do .hyper no
Tableau real, que exige TABLEAU_INTEGRATION=1 + TABLEAU_IT_PROJECT.
Lint e formatação com Ruff:
uv run ruff check .
uv run ruff format .Convenções
Padrões de código e de testes ficam nas skills do projeto
(code-standards e
testing-standards). Consulte também
o AGENTS.md para a visão geral e boas práticas adotadas.
Available Tools
10 toolsaudit_workbook_complexityA
Audita os indicadores de complexidade de um workbook contra boas práticas.
Baixa e parseia o workbook (como inspect_workbook_structure) e compara as
métricas medidas (worksheets, filtros, fontes de dados) com os limiares
configurados em Settings. Sinaliza riscos de performance em findings e
define compliant=false quando algum limiar é excedido.
Inputs: workbook_id (required). Returns: result
get_datasource_dictionaryA
Retorna o dicionário de campos de uma fonte de dados (nome, fórmula, descrição).
Consulta a Metadata API e devolve cada campo com seu nome, indicação de campo
calculado e, quando disponíveis, a fórmula e a descrição homologada.
formula/description podem ser null (campos não calculados ou sem
descrição no upstream); datatype ausente é normalizado para "unknown".
Inputs: datasource_id (required). Returns: result
get_downstream_lineageA
Lista os conteúdos que dependem de uma fonte de dados (linhagem descendente).
Consulta a Metadata API para descobrir os workbooks construídos sobre a fonte
de dados informada, devolvendo cada dependente de forma atribuível (id, nome,
tipo, projeto e owner). Uma fonte sem dependentes retorna dependencies=[]
com status="success" — ausência de dependentes não é erro.
Inputs: datasource_id (required). Returns: result
get_upstream_lineageA
Lista as fontes de dados das quais um conteúdo depende (linhagem ascendente).
Consulta a Metadata API para descobrir as fontes de dados consumidas pelo
conteúdo informado, devolvendo cada origem de forma atribuível (id, nome,
tipo, projeto e owner). Um conteúdo sem fontes ascendentes retorna
dependencies=[] com status="success".
Inputs: content_id (required), content_type. Returns: result
inspect_workbook_structureA
Inspeciona a estrutura interna de um workbook publicado no Tableau.
Baixa o artefato do workbook do servidor, parseia o XML local e reporta
worksheets, dashboards, conexões, campos e filtros, além de uma lista de
issues (campos quebrados, filtros sem lógica, conexões inválidas). A
presença de issues é diagnóstica e não faz a ferramenta falhar: o
relatório é retornado com issues populado.
Inputs: workbook_id (required). Returns: result
publish_datasourceA
Publica uma nova fonte de dados ou sobrescreve uma existente em um projeto.
Análoga a publish_workbook para .tds/.tdsx. Mesmas regras de resolução
de projeto, sobrescrita explícita (RF7) e chunking transparente.
Inputs: file_path (required), project_name (required), overwrite. Returns: result
publish_workbookA
Publica um novo workbook ou sobrescreve um existente em um projeto.
O arquivo deve ser .twb/.twbx e existir localmente. O projeto de destino
é resolvido por nome para o LUID antes da publicação. Com overwrite=false,
se já houver workbook de mesmo nome no projeto, a operação é recusada com
OVERWRITE_NOT_ALLOWED (RF7); com overwrite=true, é criada uma nova versão.
Artefatos acima de 64 MB usam chunking transparente (chunked=true).
Inputs: file_path (required), project_name (required), overwrite. Returns: result
render_view_imageA
Renderiza o PNG de uma view e devolve diagnóstico + bloco de imagem MCP.
Renderiza a view identificada por view_id, aplicando os filters como
parâmetros vf_ na requisição. Sobre os bytes aplica a heurística de tela em
branco (detect_blank_render) e devolve o RenderImageResult (JSON) junto do
bloco de imagem PNG para consumo multimodal. Uma tela provavelmente em branco
(diagnostic.severity == "error") não falha a ferramenta — a imagem é
sempre devolvida para confirmação visual pelo agente.
Inputs: view_id (required), filters, high_res.
render_workbook_pdfA
Renderiza o PDF de uma view e devolve status + bloco de arquivo PDF.
Renderiza a view identificada por view_id como PDF no formato de página
page_type (padrão A4), aplicando os filters como parâmetros vf_.
Devolve um status simples ({"status": "success", "view_id", "page_type"})
acompanhado do bloco de arquivo PDF (application/pdf) para consumo pelo
agente.
Inputs: view_id (required), filters, page_type.
search_similar_contentA
Busca conteúdo semelhante por nome para evitar duplicação (busca fuzzy).
Lista os candidatos via REST e os ranqueia por similaridade ao termo, do maior
para o menor score. Opcionalmente filtra por tipo de conteúdo. Nenhum
semelhante encontrado retorna matches=[] com status="success" — ausência
de similar não é erro.
Inputs: query (required), limit, content_type. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct operation, but audit_workbook_complexity and inspect_workbook_structure both analyze workbooks, potentially causing confusion if descriptions are not read carefully. Other tools are clearly differentiated.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., publish_workbook, render_view_image), making it easy for an agent to infer functionality.
10 tools is well-scoped for a Tableau server, covering inspection, publication, lineage, and rendering without being excessive or insufficient.
Core workflows like inspect, publish, and lineage are covered, but missing delete or update operations for workbooks and datasources create minor gaps that agents can work around.
Maintenance
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for building and testing AI agents with multi-model experimentation and insights.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server for Tableau Server. Enables AI assistants to interact with Tableau workbooks, views, datasources, and metadata.2417 PyPIMIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server for integrating Tableau with GenAI applications, enabling data visualization and analytics tasks.-
- AlicenseNot gradedqualityCmaintenanceA local MCP server that allows LLMs to inspect and safely edit Tableau Desktop workbooks (.twb) via XML, including creating native calculated fields using Tableau formula syntax.MIT
- FlicenseBqualityBmaintenanceA production-grade MCP server that exposes Tableau Server/Cloud as a BI platform, enabling project, workbook, data source, user, group, job, lineage, and export operations via natural language, with role-based permissions and token optimization.69-