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 .hyper locais (de CSV/Parquet, dados inline ou bancos externos) antes de publicar.

🚀 Começando agora? Veja o QUICKSTART para rodar o servidor via uvx e configurar nos principais agentes (Claude, GitHub Copilot, Cursor, Kiro e outros).

Stack

• Linguagem: Python >= 3.13

• Framework MCP: FastMCP (>= 3.4.2), transporte stdio

• Integraçã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, pydantic

• Gerenciador de pacotes: uv

⚠️ O tableauhyperapi embarca um runtime binário (~150 MB) e só roda em plataformas x64/arm64 de Linux, macOS e Windows. Ver QUICKSTART.

Related MCP server: powerbi-mcp-local

Instalação

Requer uv e Python >= 3.13.

uv sync

Configuraçã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 .env

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 um VolumeAlert e a operação só prossegue com confirm_large_operation=true.

Execução

Inicia o servidor MCP em transporte stdio:

uv run python main.py

Capacidade 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).

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/base

Drivers 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:

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 .hyper intermediá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 ferramentas

Testes

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 real

A 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.