Tableau MCP Server

A production-grade Model Context Protocol server that exposes Tableau Server/Cloud to Claude (Desktop, Code, and any other MCP-compatible client) as a real business-intelligence platform: projects, workbooks, worksheets/dashboards, published data sources, users and groups, background jobs and refresh schedules, Metadata API (GraphQL) lineage, Pulse metrics/insights, and CSV/PNG/PDF/Hyper exports — all constrained by the signed-in identity's actual Tableau site role and content permissions.

What this is (and isn't)

This is a deliberately-scoped core build: every tool listed below is a real, working implementation against tableauserverclient and Tableau's Metadata API — nothing is a stub that returns fake data. What's not included yet is documented explicitly in Roadmap below, rather than shipped as a half-finished tool that looks complete but isn't.

Quick start

python -m venv .venv
.venv/Scripts/activate        # .venv/bin/activate on macOS/Linux
pip install -e ".[dev]"       # add ",hyper" to also enable Hyper-extract tools

cp .env.example .env
python scripts/generate_keys.py   # paste FERNET_KEY / JWT_SECRET into .env
# then set TABLEAU_SERVER_URL, TABLEAU_SITE_NAME, TABLEAU_PAT_NAME, TABLEAU_PAT_SECRET

pytest                        # run the test suite
python -m src.server          # start over stdio (for Claude Desktop/Code)

Point Claude Desktop / Claude Code at it

A ready-to-use .mcp.json is already in the repo root for Claude Code (auto-discovered on open). For Claude Desktop, or to adapt the config for a different machine, see docs/CLAUDE_SETUP.md for copy-paste-ready configs and how to verify the connection.

Connecting to Tableau Cloud specifically

Works the same as Tableau Server, with two things to get right — both covered in docs/CONFIGURATION.md:

1. TABLEAU_SITE_NAME must be your site's actual content URL — Cloud has no "Default" site (the server logs a warning at connect time if this looks misconfigured).
2. Use a PAT (TABLEAU_PAT_NAME/TABLEAU_PAT_SECRET), not username/password — Cloud's MFA/SSO enforcement breaks password sign-in for automation.

TABLEAU_API_VERSION should also be left blank (the default) so the server auto-negotiates against Cloud's continuously-updating REST API version instead of drifting out of date against a pinned one.

Docker

docker compose up --build

Runs over HTTP (MCP_TRANSPORT=http) behind bearer-JWT auth, with a Redis sidecar for shared caching. See docs/SECURITY.md for how to issue tokens.

Deploy

The MCP server itself (above) runs locally over stdio for Claude Desktop/Code — there's nothing to deploy for that. For everything about deploying the web app (webapp/ + frontend/) — including a full free-tier walkthrough (Supabase + Render + Vercel) — see DEPLOY.md.

Documentation

• DEPLOY.md — deploying the MCP server and the web app, free-tier walkthrough included
• docs/WEBAPP.md — the multi-user web app: architecture, quick start, configuration
• docs/ARCHITECTURE.md — layering, request flow, async model, caching
• docs/TOKEN_OPTIMIZATION.md — the token optimizer: strategies, budgets, cost reporting, how to extend it
• docs/TOOLS_REFERENCE.md — every MCP tool, resource, and prompt, with required Tableau role
• docs/SECURITY.md — secrets, auth, authorization model, audit trail
• docs/CONFIGURATION.md — every environment variable, explained
• docs/TROUBLESHOOTING.md — common errors and what they mean

Design principles

• Clean layering (tools → services → repositories → tableau client), each layer only aware of the one below it — see docs/ARCHITECTURE.md.
• Repository pattern: tableauserverclient/tableauhyperapi are only ever imported inside src/repositories/ and src/tableau/; everything above speaks in Pydantic domain models (src/models/).
• Provider-agnostic token optimization (src/optimization/): every prompt is measured, deduplicated, compressed, and budget-checked before it reaches an LLM, and the savings are reported rather than assumed. New strategies plug in through a registry — see docs/TOKEN_OPTIMIZATION.md.
• Manual dependency injection via a single composition root (src/services/container.py) — explicit and easy to trace, not a framework.
• Defense in depth on authorization: Tableau's own REST API is always the final authority; src/security/permissions.py adds a fail-fast site-role check in front of it so a caller without the right role gets an immediate, clear error instead of an opaque Tableau 403.
• Every write is audited (audit_log(...)) to a dedicated, structured log file, separate from general application logs.
• Every tool response is uniform: {"success": true, "data": ...} or {"success": false, "error": ..., "error_type": ...} — raw tracebacks never reach an MCP client.
• Async-first: the blocking Tableau SDKs run on a bounded thread pool (asyncio.to_thread/ThreadPoolExecutor) so the MCP event loop stays responsive under concurrent tool calls; the Metadata GraphQL client is native aiohttp.

Project structure

src/
  config/       Pydantic Settings — every value from the environment, nothing hardcoded
  security/     Fernet encryption, JWT issue/verify, Role→Permission matrix
  logging_config/  loguru setup: redacted app logs + dedicated audit trail
  cache/        In-memory or Redis-backed async cache, TTL + prefix invalidation
  tableau/      Connection lifecycle (sign-in, re-auth, retry) + Metadata GraphQL client
  models/       Pydantic domain models (framework-agnostic)
  optimization/ Provider-agnostic token optimizer: tokenizer, pricing, pluggable strategies
  repositories/ tableauserverclient/tableauhyperapi calls, translated to domain models
  services/     Business logic: authorization, caching, audit logging, DI container
  tools/        MCP @mcp.tool() functions — one module per Tableau resource type
  resources/    MCP @mcp.resource() — read-only context (site config, project tree, identity)
  prompts/      MCP @mcp.prompt() — reusable guided BI workflows
  server.py     FastMCP app assembly + stdio/HTTP transport entrypoint
tests/
  unit/         Fast, mock-based tests (config, security, cache, services, tool_helpers)
  integration/  TableauConnectionManager against a faked TSC.Server (no network needed)
  webapp/       Web app tests: auth, chat loop, artifacts, rate limiting
webapp/         Multi-user web app (FastAPI) — see docs/WEBAPP.md
frontend/       Web app UI (Next.js)
alembic/        Postgres schema migrations for webapp/ — see "Deploy" above
docs/           Architecture, tools reference, security, configuration, troubleshooting
scripts/        generate_keys.py / generate_webapp_keys.py — secret generation

Roadmap

Deliberately deferred to a follow-up phase rather than included as thin/undertested stubs (see the "Deep core first" scoping decision this build made):

• Hyper extract writing — building new .hyper files from arbitrary data (tableauhyperapi.Inserter). Extract reading (list_hyper_tables, preview_hyper_extract) is implemented today.
• Statistical/ML analytics tools — forecasting, anomaly detection, clustering, regression, root-cause analysis. pyproject.toml's analytics extra already pins the libraries (scipy, statsmodels, scikit-learn, polars, duckdb) these would build on.
• Additional export formats — PowerPoint, Parquet, JSON (CSV, PNG, PDF, and Hyper are implemented).
• Kubernetes manifests — Docker + docker-compose are provided; a Helm chart / raw manifests are not yet.
• SSO/OIDC-federated Tableau auth flows beyond PAT and username/password (the auth_setting field on create_user supports federated site configuration, but this server doesn't itself broker an OIDC/SAML login).

License

Proprietary — internal enterprise use.