List Available Fields
Lists the datasource fields available for authoring from a live or cached workbook open in the local Tableau Studio instance — useful for field exploration, answering field questions, and non-template authoring. It does not report worksheet placements. It reports dimensions and measures across every datasource in the workbook and, in the default full verbosity, includes the fully-qualified field reference (column_ref) needed to author calculations and other field-based edits; slim returns insight candidates. This tool is available at any time and is not needed before binding a template.
A slim listing can be narrowed further to the workbook's published datasources: hasLuid keeps only the datasources Tableau Studio reports a LUID for, and luids picks out specific ones by LUID. Both are slim-only and both need a live Tableau Studio session.
Although this tool only lists fields, it is not marked read-only. When called with a session and a workbookFile, it re-snapshots the live workbook and rewrites that cache file (plus a small companion file recording which Tableau Studio session produced it) before listing.
APIs called
This tool acts on the workbook open in the local Tableau Studio instance, communicating with Tableau Studio directly rather than calling the Tableau Cloud or Server REST API. Under the hood these are calls to the local Tableau Studio External Client API — a REST API the running Tableau Studio instance serves at http://127.0.0.1:<port>/v<x> (where <x> is the latest API version). These calls carry no OAuth scopes; each is authorized by that Tableau Studio session's per-session bearer token over the loopback interface. Which calls are made depends on the arguments: a live read when a session is given (or when no cache file is passed), a refresh-then-read when both a session and a workbookFile are given, and a pure local-file read when only a workbookFile is given. A slim listing that sets hasLuid adds one further live read, of the workbook's datasource inventory.
- Reads the open workbook's XML from the running Tableau Studio session — when a
sessionis provided, or when noworkbookFileis passed.GET /v<x>/workbook/document— read the open workbook's XML. API reference
- When both a
sessionand aworkbookFileare given, re-snapshots the live workbook and rewrites the cache file before listing, so a datasource connected after the cache was written is not missed. A refresh failure is reported as an error rather than silently listing stale fields.GET /v<x>/workbook/document— re-read the live workbook to refresh the cache. API reference- Local filesystem; no API call — rewrites the cache file and its session companion file.
- When only a
workbookFileis given (nosession), reads that cache file as-is.- Local filesystem; no API call.
- When
hasLuidis set on aslimlisting, reads the open workbook's datasource inventory from the running Tableau Studio session, so each field group can be matched to the LUID of the published datasource behind it.GET /v<x>/workbook/datasources— list the datasources the open workbook connects to, with the LUID of each published one. API reference
- Parses the workbook XML into the dimension/measure field list. Parsed in-process; not an API call.
Optional arguments
session
Identifier of the target Tableau Studio session. When omitted, the session is resolved automatically (for example, when exactly one Tableau Studio instance is connected). When provided, fields are read from the live session workbook; if a workbookFile is also given, that cache file is refreshed from the live workbook first.
Example
"studio-1"
Refreshing a cache file
When a session and a workbookFile are both supplied, the tool re-snapshots the live workbook, overwrites the cache file and its session companion file, and lists fields from the fresh XML. This closes the gap where a datasource connected after the cache was first written would otherwise be invisible to a cache-only read.
If the live re-snapshot fails, the tool returns an error — it never silently falls back to the stale cache. Retry without session to read the existing cache file as-is.
LUID filtering requires a live Tableau Studio session.
workbookFile
Absolute path to a cached workbook XML file on the local filesystem. Behavior depends on whether a session is also given: with a session, the file is refreshed from the live workbook before listing; without a session, the file is read exactly as-is. Omit workbookFile to read fields from the live session workbook. The file must already exist — the tool returns an error if the path is missing.
Example
"/Users/me/.tableau-mcp/cache/workbook-abc123.xml"
LUID filtering with workbookFile requires an explicit live session.
verbosity
How much detail each field carries: full (default) or slim.
full— returns a human-readable table of dimensions and measures plus afieldsarray carrying full metadata, including the fully-qualifiedcolumn_reffor each field.slim— returns compact candidate tuples grouped by datasource, sorted into the three buckets an insight or a simple viz needs, and omittingcolumn_ref.
Defaults to full. hasLuid and luids are accepted only alongside slim; supplying either with full is refused before anything is read.
Example
"slim"
Output shapes
The two verbosities return different result shapes:
fullproduces{ message, fields }—messageis a formatted dimensions/measures table (or a "no fields found" note for an empty workbook), andfieldsis a flat array spanning all datasources, each field carrying its owndatasource,column_ref, and (for a published datasource)contentUrl.slimproduces{ datasources }— one group per datasource, in first-seen order, so the datasource identity is carried once per group rather than repeated on every field. A single-datasource workbook is still one group, so callers always parse the same structure. Each group holds three arrays of positional tuples:measures([caption, localName, aggregation, "base" | "aggregatedCalc"]) for numeric measures,timeDimensions([caption, localName, "date" | "datetime"]), andbreakdownDimensions([caption, localName, "nominal" | "ordinal"]). A field that fits none of those three buckets is left out of the slim result entirely. WhenhasLuidis set, each surviving group also carriesluidand the datasource's friendlyname.
hasLuid and luids require verbosity: slim. Supplying either with full is refused with hasLuid and luids require verbosity: slim.
hasLuid
Boolean. Narrows a slim listing to the datasources the running Tableau Studio instance reports a LUID for — the published, non-federated ones — and stamps each surviving group with that luid and the datasource's friendly name. Groups whose datasource carries no LUID (embedded or local datasources) are dropped. Requires verbosity: "slim". Omitting it, or passing false, leaves the slim result unfiltered.
A live session is required
Matching a field group to a LUID means reading the open workbook's datasource inventory from the running instance, so this filter cannot be served from a cache file alone. If you pass a workbookFile, you must also name an explicit session; leaving session out — or passing the placeholder value default, which counts as leaving it out — is refused before anything is read. With no workbookFile the workbook is already being read live, so no extra argument is needed.
Two situations fail rather than returning an empty list, because an empty list would read as "this workbook has no eligible fields" when the real cause is an identity mismatch. If the workbook's field datasources cannot be matched to the instance's datasource inventory at all, the error names both sets of identities. If they do match but none of the matches carries a LUID, the error names the matched datasources instead.
Example
true
luids requires hasLuid: true. Supplying luids without it is refused with luids requires hasLuid: true.
luids
Array of LUID strings, each non-empty, selecting exactly which LUID-backed datasources to return. Only groups whose datasource carries one of the listed LUIDs are kept. Requires hasLuid: true — supplying luids on its own is refused — and therefore verbosity: "slim" as well. An empty array behaves the same as omitting the argument: every LUID-backed datasource is returned.
Every requested LUID must match
If any LUID in the array matches no datasource in the open workbook, the whole call fails with an error listing the LUIDs that did not match, alongside those that did. The tool does not return a partial result for the LUIDs that happened to match.
Example
["9a8b7c6d-1234-4a5b-8c9d-0e1f2a3b4c5d"]
Notes and caveats
- Field datasource identities have to match the workbook's datasource metadata. When they do not, the tool refuses with
Could not match workbook field datasource identities (<field identities>) to workbook datasource metadata (<workbook identities>). - One field datasource must match one workbook datasource. When a field datasource matches more than one, the tool refuses with
Datasource "<name>" matched multiple workbook datasources: <identities>.
Example results
Full verbosity (default)
{
"message": "Found 2 fields in \"Sample - Superstore\":\n\nDIMENSIONS (1):\nName | Local Name | Type\n-------------------------------+--------------------------------+----------------\nCategory | (same) | N (Text)\n\nMEASURES (1):\nName | Local Name | Type\n-------------------------------+--------------------------------+----------------\nProfit | (same) | Q (Number (decimal))\n",
"fields": [
{
"datasource": "Sample - Superstore",
"contentUrl": "SuperstoreDS",
"columnName": "[Profit]",
"columnInstanceName": "[sum:Profit:qk]",
"derivation": "Sum",
"type": "quantitative",
"role": "measure",
"datatype": "real",
"isAggregated": false,
"column_ref": "[Sample - Superstore].[sum:Profit:qk]"
},
{
"datasource": "Sample - Superstore",
"contentUrl": "SuperstoreDS",
"columnName": "[Category]",
"columnInstanceName": "[none:Category:nk]",
"derivation": "None",
"type": "nominal",
"role": "dimension",
"datatype": "string",
"isAggregated": false,
"column_ref": "[Sample - Superstore].[none:Category:nk]"
}
]
}
Slim verbosity (verbosity: "slim")
{
"datasources": [
{
"datasource": "federated.0abc123",
"measures": [["Profit", "Profit", "Sum", "base"]],
"timeDimensions": [["Order Date", "Order Date", "date"]],
"breakdownDimensions": [["Category", "Category", "nominal"]]
}
]
}
LUID-filtered slim verbosity (verbosity: "slim", hasLuid: true)
Each surviving group gains the datasource's luid and its friendly name; datasources without a LUID are gone:
{
"datasources": [
{
"datasource": "federated.0abc123",
"measures": [["Profit", "Profit", "Sum", "base"]],
"timeDimensions": [["Order Date", "Order Date", "date"]],
"breakdownDimensions": [["Category", "Category", "nominal"]],
"name": "Sample - Superstore",
"luid": "9a8b7c6d-1234-4a5b-8c9d-0e1f2a3b4c5d"
}
]
}
No fields found (full verbosity)
{
"message": "No fields found in the workbook datasources.",
"fields": []
}
Related
get-xml— read the full structure (XML) of the open workbook.get-datasources— list the datasources in the open workbook.