Tableau Graphql Mcp

io.github.tdriesPublished by GitHub account tdriesv0.2.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyDatabasesData & Analytics

Overview

AI-generated overview

Turns a Tableau site's Metadata API into read-only MCP tools so an assistant can answer lineage and impact questions in plain language.

What you can do
  • Run any read-only Metadata API GraphQL query, with partial-result flags when the node limit is hit
  • Inspect the live schema and pull curated query templates and worked examples
  • Find which workbooks and datasources use given columns, fields or tables
  • Trace multi-hop impact of a column, field or table, including affected sheets, dashboards, workbooks and owners to notify
  • Search content by name substring across workbooks, datasources and tables, with coverage counts
  • Check the connected server, site, versions, endpoint and auth status
When to use it
Useful when you need to know what breaks before changing a Tableau column, field or table, which sources a workbook depends on, or who to notify — answered from live metadata rather than a fixed report.
Requirements
Runs locally over stdio via uvx (Python package, uv required). Needs TABLEAU_SERVER, TABLEAU_PAT_NAME and TABLEAU_PAT_SECRET, plus TABLEAU_SITE_CONTENT_URL for non-default sites; SSO tenants can use TABLEAU_AUTH_TOKEN or TABLEAU_COOKIE instead. HTTPS access to the Tableau host; on Tableau Server an admin must enable the Metadata API.
Before you install
The PAT secret (TABLEAU_PAT_SECRET) or session cookie grants access to everything your Tableau account can see, so keep it in the client's env block and scope the account's permissions. Results are limited to your own Tableau permissions. Read-only by design, but queries and metadata are sent to your Tableau host over HTTPS.

Installation

In SourceWeft

  1. Open Tableau Graphql Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[tableau-graphql-mcp]

tableau-graphql-mcp

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

[CI] [CodeQL] [OpenSSF Best Practices] [OpenSSF Scorecard] [Ruff] [PyPI] [Python versions] [MCP compatible] [MIT License] [Server + Cloud] [Minimal dependencies]

[Add to Cursor]

[Asking lineage questions in Claude]

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:

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

Env varRequiredDefaultDescription
TABLEAU_SERVERyesn/ahttps://tableau.company.com (Server) or https://<pod>.online.tableau.com (Cloud).
TABLEAU_SITE_CONTENT_URLno""Site slug (the part after /#/site/). Empty = Default site (Server only); Cloud always has one.
TABLEAU_PAT_NAMEyes¹n/aPersonal Access Token name.
TABLEAU_PAT_SECRETyes¹n/aPAT secret: the whole string, do not split on :.
TABLEAU_TIMEOUTno60Per-request timeout (seconds).
TABLEAU_API_VERSIONnoautoREST API version; else read from /api/serverinfo.
TABLEAU_METADATA_PATHnoautoOverride the GraphQL path; else auto-detected.
TABLEAU_ALLOW_HTTPnooffSet to 1 to allow a plain http:// server on a trusted internal network. Otherwise only HTTPS (or loopback) is accepted, so credentials never travel unencrypted.
TABLEAU_LOG_LEVELnoINFODEBUG logs each HTTP call (method + URL; never headers, bodies or secrets) to stderr.
TABLEAU_AUTH_TOKENnon/aAdvanced: a pre-obtained X-Tableau-Auth token (SSO tenants where PATs are disabled).
TABLEAU_COOKIEnon/aAdvanced: a browser session cookie (SSO fallback).

¹ 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\):

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

ToolWhat it doesKey args
graphql_queryRun any read-only Metadata API GraphQL query. The general tool for any lineage question.query, variables
introspect_schemaLive schema introspection: list entry points, or a type's exact fields.type_name
lineage_examplesA schema cheat-sheet plus 28 curated question-to-GraphQL templates (8 categories).category
where_usedWhich workbooks/datasources use given column / field / table names (robust one-hop core-lineage resolution).names
impact_analysisFull transitive multi-hop blast radius of a column/field/table: every dependent field, plus affected sheets, dashboards, workbooks, and owners to notify.name
search_contentFind content whose name contains a term (case-insensitive substring), across workbooks, datasources, tables (and optionally fields/columns), with coverage numbers.term, types
server_infoConnected server, site, versions, endpoint, auth, and whether Catalog lineage is available.none

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

[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

SymptomFix
Server doesn't appearFully quit and relaunch the client; check the config path and JSON validity.
spawn uvx ENOENTInstall uv, or use the absolute path to uvx.
Sign-in fails (401)Check the PAT name/secret and TABLEAU_SITE_CONTENT_URL. On SSO tenants PATs may be disabled; use TABLEAU_AUTH_TOKEN/TABLEAU_COOKIE.
"Could not reach the Metadata API"On Tableau Server, an admin must enable it: tsm maintenance metadata-services enable. On Cloud it is always on.
Empty downstreamWorkbooksExpected without the Data Management add-on; use the where_used tool, which resolves via core lineage.

Inspect the server directly with the MCP Inspector:

bash
npx @modelcontextprotocol/inspector uvx tableau-graphql-mcp

Development

bash
git clone https://github.com/tdries/tableau-graphQL-mcp && cd tableau-graphQL-mcpuv sync --all-extrasuv run tableau-graphql-mcp                     # run from sourceuv run pytest --cov=tableau_graphql_mcp        # tests + coverage (offline; no Tableau needed)uv run ruff check .                            # lintuv 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.

Source: README.md at commit 992a1e6

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

2
  1. v0.2.0LatestOct 14, 2026
  2. v0.1.2Sep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts