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-g