Use Tableau Studio Headless


On This Page

Tableau Studio offers three ways to drive authoring actions for workbooks and extensions headlessly, without using the Tableau Agent interface and with or without Tableau Desktop:

While driving Studio headlessly does not get the benefit of Tableau Agent’s guardrails and management of Tableau MCP’s behavior, it enables you to author using natural language or programmatic tooling of your choice.

Drive Tableau Studio using your AI tool of choice

You can use Claude, Codex or any MCP-capable AI tool to drive Tableau Desktop. A local install of the Tableau MCP enacts your natural language prompts by calling the External Client API(opens in new window) served by Tableau Desktop.

Prerequisites

Turn on the External Client API

In the Tableau Desktop toolbar, select → Help → Settings & Performance → External Client API Access (Requires Restart).

Install Tableau MCP locally

  1. Clone the repo and switch to the feature/desktop branch:

     git clone https://github.com/tableau/tableau-mcp
     cd tableau-mcp
     git checkout feature/desktop
    
  2. Install dependencies and build the Desktop profile:

     npm ci
     npm run build
    
  3. Point your MCP client at the built server. For Cursor, save the following as .cursor/mcp.json, or merge it into that file. Replace the path with the folder where you cloned the repo. In Claude Code or another MCP client, use the same command, args, and env in that client’s config.

     {
       "mcpServers": {
         "tableau-desktop": {
           "type": "stdio",
           "command": "node",
           "args": ["<path-to-your-tableau-mcp-clone>/build/index.desktop.js"],
           "env": {
             "TRANSPORT": "stdio",
             "TABLEAU_EXTERNAL_API": "true"
           }
         }
       }
     }
    

Connect your AI tool

  1. Relaunch Tableau Desktop with the External Client API enabled.
  2. Open your MCP client and confirm that tableau-desktop connects. The server reads the discovery file and finds the running Desktop instance.
  3. Try a query prompt, such as “What workbooks are available in Tableau Studio?”
  4. Try an action prompt, such as “Change the font color of all dashboard titles in the workbook to green.”

Author using Tableau MCP without Tableau Desktop

You can use your AI tool to create and modify Tableau content using the Tableau authoring reasoning and expertise built natively in Tableau MCP. Tableau Plugins for Claude and Codex greatly enhance these capabilities and are available the tableau-plugin repo or through Claude and Codex marketplaces.

Call Tableau Desktop’s External Client API directly

For automation scenarios you may choose to create scripts or other programmatic content that drives Tableau Studio through the External Client API(opens in new window) . For instance, you may want to apply a style guide to a workbook, check a batch of workbooks for accessibility features, or search and replace a string in a set of Tableau projects.

Get Started with direct calls to the External Client API

On an internal build, turn on the API before these calls. See Turn on the External Client API.

  1. Install Tableau Studio.
  2. Open Tableau Studio.
  3. Find your External Client API discovery file.

    This file is recreated with fresh values on each launch of Tableau Studio and is only available once the app has fully started. The basename of the file is the OS process ID Tableau is running in.

    macOS

    ~/Library/Application Support/Tableau/Tableau/ExternalApi/<pid>.json

    Windows

    %LOCALAPPDATA%/Tableau/Tableau/ExternalApi/<pid>.json

    The two important values it contains are:

    • baseUrl - typically http://127.0.0.1:<xxxxx>
    • token - looks like: af1129c44d5dcd8bd9206a8641133c91eed66c76b5f562633a37fd186e5ccac1

    A full typical discovery file looks like:

     {
     "schemaVersion": 1,
     "instanceId": "td_a8f1bf61-9194-49e8-8205-6ae7e831d5c2",
     "pid": 28814,
     "baseUrl": "http://127.0.0.1:62197",
     "tokenType": "Bearer",
     "token": "af1129c44d5dcd8bd9206a8641133c91eed66c76b5f562633a37fd186e5ccac1",
     "applicationVersion": "0.0.0",
     "apiVersion": "0.2.6",
     "startedAt": "2026-08-14T16:14:52Z"
     }
    

    A model call looks like:

     curl -sS -H "Authorization: Bearer <token value>" \
     <baseURL>/v0/workbook
    
  4. Check the presence of the client (no authorization is needed for this one call). Run:

     curl -sS  http://127.0.0.1:62197/v0/health
    

    This should return:

     {"status":"OK"} (HTTP 200)
    
  5. Try a call to list all available workbooks. Run:

     curl -sS -H "Authorization: Bearer af1129c44d5dcd8bd9206a8641133c91eed66c76b5f562633a37fd186e5ccac1" \
     http://127.0.0.1:62197/v0/workbook
    

    This should return something like:

     {
       "title": "Book1",
       "location": null,
       "unsavedChanges": false,
       "worksheets": [
         {
           "id": "{9BBEEE50-4AF9-46C2-BB36-1DAC6793FE4B}",
           "name": "Sheet 1",
           "hidden": false,
           "isActiveSheet": true,
           "index": 0,
           "isAutoUpdatesPaused": false,
           "datasources": []
         }
       ],
       "dashboards": [],
       "storyboards": []
     }
    

API call helper script

call-studio-api.py (download) is an example script for Windows and macOS that does the discovery and authentication work on your behalf each time you call. Rather than reading the discovery file yourself and pasting a baseUrl and token into every cURL call, you supply a simplified URI and a JSON payload:

python call-studio-api.py <METHOD> <path> [json-body] [--workbook <name or path>]

There is nothing to configure first. Each run finds the running copies of Tableau Studio, confirms the External Client API is responding, and supplies the current baseUrl and token.

For long-running operations that return HTTP 202 instead of a result, the script waits and delivers the full response when it arrives, for up to 30 seconds.

The script writes the response body to stdout and status lines, prompts, and errors to stderr, so python call-studio-api.py GET v0/health | jq .status works. It writes no files, sets no environment variables, and saves no token between runs. Because each run rediscovers the current session, it keeps working after Tableau Studio restarts with a new process ID and a new token.

Prerequisite

The script needs Python 3.9 or later.

Arguments

Argument Required Description
METHOD Yes HTTP method: GET, POST, PUT, PATCH, or DELETE.
path Yes Simplified API path. The leading slash is optional, so v0/workbook and /v0/workbook are equivalent.
json-body No JSON string for write methods. Checked for valid JSON before anything is sent.
--workbook No Drive the window holding this workbook. Accepts a file name (lab.twb), a path (~/books/lab.twb, resolved from your current directory), or the title shown in Tableau Studio (Book1). A workbook that has never been saved has no file name or path, so its title is the only way to name it.

Choose which window to drive

If more than one instance of Tableau Studio is open, the script will prompt:

Multiple Tableau Studio instances are open. Choose one:
  1) lab.twb (/Users/me/books/lab.twb)
  2) sales.twb (/Users/me/books/2026/sales.twb)
  3) Book1 (unsaved)
Enter 1-3:

--workbook skips that prompt. If the value matches nothing that is open, the script will prompt you to select an open instance.

Examples

Focus Sheet 1 in the current workbook:

python call-studio-api.py POST v0/workbook:goToSheet '{"id":"{9BBEEE50-4AF9-46C2-BB36-1DAC6793FE4B}"}'

Read the structure of a specific open workbook:

python call-studio-api.py GET v0/workbook --workbook ~/books/lab.twb

List the workbooks on the site, waiting for the operation to finish:

python call-studio-api.py GET v0/site/workbooks

Exit codes

Useful when calling the script from other automation:

Code Meaning
0 The instance answered with a 2xx, and any operation the script waited on succeeded.
1 Tableau Studio is not running or stopped responding, no workbook matched your selector, the prompt was cancelled, or an operation outlived its timeout.
2 The command itself was malformed, such as a missing argument or a body that is not valid JSON.
3 The instance returned an error status, or the operation it started failed.

Check the External Client API(opens in new window) reference for the Tableau authoring operations you can call.