io.github.tdries/tableau-graphql-mcp

tableau-graphql-mcp

Ask any Tableau lineage question, in any MCP client, through the Tableau Metadata API.

tableau-graphql-mcp turns your Tableau site's Metadata API into a set of MCP tools, so an AI assistant (Claude, Cursor, Cline, and others) can answer lineage questions in plain language:

• "If I drop the column SALES, which workbooks break?"
• "What tables does the Sales Overview workbook depend on?"
• "Which calculated fields reference Profit, and on which dashboards?"
• "Who should I notify before changing the DIM_CUSTOMER table?"

It ships seven curated tools: a universal GraphQL passthrough, live schema introspection, an embedded library of correct query templates, a robust where_used resolver, a multi-hop impact_analysis, a substring content search, and a connection probe. Together they let the model answer any lineage question, not just a fixed menu.

Why it's different

• Any question, done right. graphql_query runs any read-only GraphQL; introspect_schema and a built-in cheat-sheet plus 28 worked examples keep the model's queries correct.
• True impact analysis (multi-hop). impact_analysis follows the whole dependency chain (a calc built on a calc built on a column is included) and returns the full blast radius plus the de-duplicated owners to notify, not just direct references.
• Works everywhere. Tableau Server and Cloud. The REST API version and the GraphQL endpoint (/api/metadata/graphql, with a /relationship-service-war/graphql fallback) are auto-detected.
• Robust lineage without Catalog. where_used resolves workbooks via core lineage (referencedByFields -> sheets -> workbook), so it works even when the Data Management add-on's downstreamWorkbooks is empty.
• No silent truncation. graphql_query flags partial_results when a query hits the node limit, and search_content reports scanned/total coverage, so a truncated answer is never mistaken for a complete one.
• Tiny and safe. Read-only, stdio-only (no inbound port), secrets from env only, and no dependencies beyond the MCP SDK (stdlib urllib for HTTP).

Quickstart

You need uv (curl -LsSf https://astral.sh/uv/install.sh | sh) and a Tableau Personal Access Token.

Claude Code, one line:

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

That's all. uvx fetches the package from PyPI and runs it in an isolated environment; nothing to clone or install (and no git required). Then ask Claude a lineage question.

Configuration

All configuration is via environment variables (set them in your client's env block, never on the command line).

¹ Provide a PAT (TABLEAU_PAT_NAME + TABLEAU_PAT_SECRET) or an advanced TABLEAU_AUTH_TOKEN / TABLEAU_COOKIE.

Claude Desktop

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "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"
      }
    }
  }
}

Fully quit and reopen Claude Desktop, then check the tools menu.

Cursor · Cline · Windsurf

Every client uses the same mcpServers schema shown above. Add the same block to:

• Cursor: ~/.cursor/mcp.json (global) or .cursor/mcp.json (project).
• Cline: the MCP Servers panel, then Configure, into cline_mcp_settings.json.
• Windsurf: ~/.codeium/windsurf/mcp_config.json.

On Windows, if uvx isn't found by the GUI app, use its absolute path (e.g. %USERPROFILE%\.local\bin\uvx.exe).

Tools

All tools are read-only. The Metadata API has no mutations.

Example prompts

Once connected, try:

• "Use server_info to confirm what you're connected to."
• "Search for anything with 'revenue' in the name."
• "Which workbooks use the columns SALES, PROFIT and DISCOUNT? Group by owner."
• "Show me the field-to-source-column map for the 'Sales Overview' workbook."
• "List every calculated field in that workbook with its formula."
• "Which published datasources feed workbooks in the Analytics project, and which are uncertified?"
• "Run impact_analysis on the 'Profit Ratio' field: every dependent sheet, dashboard, workbook, and owner to notify."
• "What is the blast radius of dropping the DIM_CUSTOMER table: workbooks, sheets, and owners to notify?"

Architecture

The server speaks MCP over stdio to the client and HTTPS to Tableau: it signs in with your PAT to get an X-Tableau-Auth token (auto-refreshed on expiry), auto-detects the REST API version and the GraphQL endpoint, then forwards queries to the Metadata API. Nothing is stored; every answer is live.

Security

• Read-only, enforced. Only GraphQL queries: no writes, no shell. graphql_query rejects mutation/subscription operations, and the Metadata API is query-only regardless.
• Declared read-only. Every tool carries the MCP readOnlyHint annotation, so clients can verify it without reading the code.
• Local and stdio-only. No inbound network port is opened.
• Secrets from env only. Never passed as tool arguments, never logged, never returned in output.
• Credentials go only to your Tableau host. HTTPS is required, certificates are verified, and redirects are refused.
• Least privilege. The PAT inherits your Tableau permissions; the API only returns content you can see.
• Verifiable releases. Every GitHub release carries Sigstore signatures and a CycloneDX SBOM, and PyPI uploads use Trusted Publishing.
• Pin a version in production: uvx tableau-graphql-mcp==0.2.0.

See SECURITY.md for the threat model, data handling, disclosure policy and how to verify a release.

Troubleshooting

Inspect the server directly with the MCP Inspector:

npx @modelcontextprotocol/inspector uvx tableau-graphql-mcp

Development

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

The same gates run in CI (Linux/macOS/Windows, Python 3.10 to 3.13): ruff check, ruff format --check, mypy --strict, and pytest with a coverage floor. The package ships a PEP 561 py.typed marker, so importing it gives your type checker full types. CodeQL scans every push, and a weekly fuzzing job (fuzz/) attacks the read-only guard.

Contributions welcome: see CONTRIBUTING.md and the Code of Conduct.

Roadmap

Shipped: published on PyPI and listed on the official MCP registry. Next:

• [ ] Optional Data Management path: richer downstreamWorkbooks when Catalog is present
• [ ] More curated query templates in lineage_examples
• [ ] Optional response caching for repeated introspection within a session

Ideas and votes welcome in Discussions.

License

MIT © Tim Dries. Built at Biztory.