Add Field
Places a field on a worksheet shelf in the open Tableau Studio workbook — the manual path for adding a field when no template binding applies. The target argument selects the shelf or encoding channel:
rows— add the field to the Rows shelfcols— add the field to the Columns shelfencoding— add the field to an encoding channel (color, size, detail, and so on); requiresencodingType
This tool edits a cached copy of the worksheet on the local filesystem and does not apply the change to the open workbook; run apply-worksheet to write the edit back.
Although this is a single edit step, it is not read-only: it writes the modified worksheet XML to a local cache file (plus a small companion file recording which Tableau Studio session produced it). Chain multiple add-field edits on the same cache file, then apply them once with apply-worksheet.
APIs called
This tool acts on the worksheet in the open Tableau Studio workbook, communicating with Tableau Studio directly rather than calling the Tableau Cloud or Server REST API. Under the hood any calls are 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 loopback calls carry no OAuth scopes; each is authorized by the running Tableau Studio instance's per-session bearer token over the loopback interface. The field edit itself is performed in-process on a local cache file, so the External Client API is reached only on first use — when you pass a worksheetName that has not yet been cached and the sheet must be fetched from the open workbook.
- Fetches the named worksheet from the open workbook and mints a local cache file for it — only when
worksheetNameis given without aworksheetFile. Requires a workbook to be open in the target session, and the name must resolve to exactly one worksheet.GET /v<x>/workbook/worksheets— list worksheets to resolve the name to an id. API referenceGET /v<x>/workbook/worksheets/{id}/document— read that worksheet's XML. API reference
- Places the field on the chosen shelf or encoding, checks the result, and saves it — no External Client API call.
- Field placement and well-formed-XML validation run in-process (not an API call).
- Reading the cached worksheet file (and an optional workbook file) and writing the edited XML back — plus a companion file recording the Tableau Studio session — are local filesystem operations (no API call).
Required arguments
target
The shelf or encoding channel to place the field on. One of rows, cols, or encoding.
rows— the Rows shelfcols— the Columns shelfencoding— an encoding channel selected byencodingType
When target is encoding, encodingType is required.
Example
{ "target": "cols" }
columnRef
Reference to the field to add, as it appears in the worksheet or workbook XML (for example, a datasource-qualified column reference).
Example
{ "columnRef": "[Sample - Superstore].[sum:Profit:qk]" }
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).
Example
"studio-1"
worksheetName
Display name of the worksheet to edit. Name-only calls reuse the open edit buffer for that sheet; omit this argument to pass worksheetFile instead. Provide either worksheetName or worksheetFile.
Cached on first use
When you pass worksheetName without a worksheetFile, the tool reads the sheet from the open workbook (see APIs called) and writes it to a new cache file before editing. The result includes that file path, so you can stack more edits by passing it as worksheetFile on follow-up calls before a single apply-worksheet. If both worksheetName and worksheetFile are given, worksheetFile wins and no fetch happens.
Example
"Sheet 1"
Passing neither worksheetName nor worksheetFile is refused with Provide either worksheetName (to edit an existing sheet) or worksheetFile (a cached path).
worksheetFile
Filesystem path to a cached worksheet XML file from a prior edit or from get-xml. Omit it to reuse the open edit buffer. When supplied, edits accumulate on this file, so passing it lets you stack multiple field edits before applying. Provide either worksheetName or worksheetFile.
Example
"/Users/me/.tableau-mcp/cache/worksheet-Sheet_1-abc123.xml"
encodingType
Which encoding channel to place the field on: one of color, size, lod, detail, text, tooltip, path, or angle. Required when target is encoding; ignored for rows and cols.
Example
"color"
When target is encoding and encodingType is omitted, the tool refuses with encodingType is required when target=encoding. Provide one of: color, size, lod, detail, text, tooltip, path, angle.
index
Optional position at which to insert the field within the target shelf or encoding. When omitted, the field is appended.
Example
2
index must be an integer in the range 0 through the number of fields already on that shelf or encoding, inclusive. Anything else is refused with index must be an integer in the range 0..<count> for <target>.
workbookFile
Optional filesystem path to a cached workbook XML file returned by field resolution. When omitted, the tool reads the workbook live. If the file is missing or unreadable, the edit proceeds without it.
Example
"/Users/me/.tableau-mcp/cache/workbook-abc123.xml"
Example result
{
"message": "Successfully added field to Columns shelf. Updated file: /Users/me/.tableau-mcp/cache/worksheet-Sheet_1-abc123.xml. Use apply-worksheet with this file to apply changes.",
"file": "/Users/me/.tableau-mcp/cache/worksheet-Sheet_1-abc123.xml"
}
Related
apply-worksheet— applies the edited cache file back to the open Tableau Studio workbook.get-xml— reads worksheet structure and produces a cache file to edit.