Skip to main content
Glama

cwtwb

Tableau workbook engineering for reproducible .twb / .twbx generation, validation, and migration.

cwtwb is a Python toolkit and Model Context Protocol (MCP) server for building Tableau Desktop workbooks from code or agent tool calls.

It is meant to be a workbook engineering layer, not a conversational analytics agent. The focus is reproducibility, inspectability, and safe automation in local workflows, scripts, and CI.

Design Workflow Reference

The agent design workflow and the design_advisor skill are informed by Adam Mico's adammico-lab Tableau workflow skills, especially Tableau Dashboard Blueprint's build-from-a-design-spec approach. cwtwb independently adapts those ideas to reproducible .twb / .twbx authoring; it does not depend on, bundle, or copy adammico-lab code or skill content. cwtwb is not affiliated with Adam Mico, Salesforce, or Tableau.

The cw in cwtwb comes from Cooper Wenhua.

Author: Cooper Wenhua <imgwho@gmail.com>

Website · Source · Changelog

Online Tableau Workbook Checker checks a single .twb or .twbx for free with no Tableau installation or login required; uploaded inputs are processed in memory and released after processing, without reading data rows (see security details).

PyPI Downloads Website Source License Python

Star History

Star History Chart

Try the example workflow · Read the guide

Related MCP server: Tableau MCP

Quick Start

Install

Alpha 0.29.0a4 fixes the missing PatternedLineMarks declaration for patterned line styles, which could prevent Tableau Desktop from opening a generated workbook. Layered tooltips also retain measures used by another pane's axis. It retains Drive Time map-tool configuration, independent map-layer data sources, and named embedded Web Page targets from 0.29.0a3. See the feature guide and changelog.

pip install --upgrade cwtwb==0.29.0a4
uvx --from cwtwb==0.29.0a4 cwtwb

To use the stable channel instead:

pip install cwtwb

If you want the bundled Hyper-backed example too:

pip install "cwtwb[examples]"

If you want cloud validation (upload to Tableau Cloud/Server):

pip install "cwtwb[validate]"

Run As An MCP Server

uvx cwtwb

The short form above remains the simplest option and is the default config shown in this repository. cwtwb is a smart entrypoint: with no arguments in an interactive terminal it prints CLI help; when launched by an MCP client over stdio it starts the server.

Add the server to your MCP client with the same command. For example:

{
  "mcpServers": {
    "cwtwb": {
      "command": "uvx",
      "args": ["cwtwb"]
    }
  }
}

For Claude Code:

claude mcp add cwtwb -- uvx cwtwb

For VSCode, add cwtwb to your workspace or user mcp.json and use uvx cwtwb as the command.

If you prefer an explicit script name, these equivalent launch styles also work:

uvx cwtwb mcp
uvx --from cwtwb cwtwb-mcp
python -m cwtwb.mcp_server

Use As A CLI

The same package also exposes first-class command-line workflows for humans, scripts, CI, and agents that need direct file operations instead of MCP tool calls.

cwtwb --help
cwtwb doctor
cwtwb status --json
cwtwb inspect workbook.twb --json
cwtwb validate workbook.twb
cwtwb analyze workbook.twb --json
cwtwb run examples/specs/basic_cli.yaml

Common write commands require an explicit output path by default:

cwtwb create --out output/base.twb
cwtwb chart add output/base.twb --worksheet "Sales by Category" --mark Bar --rows Category --columns "SUM(Sales)" --out output/chart.twb
cwtwb dashboard add output/chart.twb --name Overview --worksheets "Sales by Category" --out output/dashboard.twb

Use --in-place only when you intentionally want to overwrite the input workbook, and --force only when replacing an existing output file.

Convert Workbooks Between Formats

convert detects TWB, TWBX, YAML, and JSON from file extensions. It does not require Gallery, a template, or an active editor session:

cwtwb convert input.twbx --out workbook.yaml
cwtwb convert workbook.yaml --out workbook.json
cwtwb convert workbook.json --out rebuilt.twbx
cwtwb convert input.twbx --out unpacked.twb

cwtwb export input.twb --out workbook.yaml is an alias. Native definitions also work with cwtwb run workbook.yaml --out rebuilt.twb. Existing automation specs keep their previous behavior. Outputs are not overwritten unless --force is supplied; conversion never overwrites its input.

Python: from cwtwb import convert_workbook, then convert_workbook("input.twbx", "workbook.yaml"). MCP exposes the same stateless convert_workbook(input_path, output_path, force=False) tool.

The versioned cwtwb-native format currently represents the native XML tree: document.root contains tag, attributes, text, ordered children, and tail; comments, processing instructions, namespaces, thumbnails, and unknown elements are retained. Edit formulas in calculation.attributes.formula and layout geometry in zone attributes. XML attribute values remain strings. This is a detailed structural format, not yet a simplified semantic workbook DSL; no claim is made that every Tableau feature is understood or safely editable. Conversion bypasses TWBEditor cleanup and does not inject generated comments. XML declaration spelling, CDATA spelling, namespace prefixes, and ZIP metadata are not promised byte-for-byte. Unknown nodes are retained, not interpreted.

Binary resources are copied to <output-name>.assets/, with relative paths and SHA-256 hashes in the definition. Keep the definition and this directory together. An unpacked TWB also has a <output-name>.resources.json companion to retain unreferenced package assets for later repacking. File references are relocated when needed; remote database connections remain remote. Standalone TWB discovery currently covers Hyper/CSV/Excel connections and bitmap zones; arbitrary external files referenced by custom extensions are not automatically discovered. TWBX conversion retains every bundled resource file, including unknown extensions.

Missing known external resources produce warnings for text output and block TWBX packaging. Duplicate keys, unknown document properties/versions, missing or changed resource files, unsafe archive paths, multiple-TWB archives, and DTD-bearing XML fail explicitly. After deliberately changing an asset, update its recorded hash. Resource directories are not garbage-collected when outputs are replaced.

Conversion checks XML syntax and resource integrity, not Tableau calculations, field-reference semantics, Desktop loading, rendering, or interactions. Use the existing validation commands and Tableau runtime checks separately. run --validate is intentionally rejected for native definitions rather than implying those checks ran during conversion.

MCP Client Stability

When cwtwb is connected as an MCP server, agents should call the exposed MCP tools directly through their client. They should not run shell commands such as mcp call cwtwb ..., mcp list-tools cwtwb, or gh api .../mcp/...; those commands are not part of cwtwb and are usually unavailable in normal Claude, Codex, Cursor, or VSCode environments.

If an agent cannot see tools such as create_workbook, add_worksheet, or save_workbook, restart or reconnect the MCP client and verify the server config. Clearing the uv cache only refreshes installed packages; it does not fix a stale client tool surface.

When using an existing .twb as a visual reference, agents must not copy Tableau XML column-instance tokens into chart inputs. Values such as [sum:Sales:qk], [none:Category:nk], [mn:Order Date:ok], or [federated.xxx].[sum:Profit:qk] are generated internals. Pass user-facing expressions such as Sales, SUM(Sales), Category, or MONTH(Order Date) instead.

Useful resources for agents:

cwtwb://tool-surface
cwtwb://skills/index
cwtwb://skills/data_quality
cwtwb://skills/design_advisor
cwtwb://skills/metric_blueprint
cwtwb://skills/dashboard_designer
cwtwb://skills/quality_review
cwtwb://skills/documentation
file://docs/tableau_all_functions.json

Compatibility aliases are also available for common guessed URIs such as cwtwb://docs/manual-editing, but new prompts should prefer cwtwb://tool-surface and cwtwb://skills/index.

For client-specific details and the full reference, see https://github.com/aidatacooper/cwtwb/blob/main/docs/guide.md.

Dashboard Layout Files

Custom dashboard layouts can now be authored as either JSON or YAML using the same declarative DSL. For agent workflows, generate a layout file first, then pass that file path into add_dashboard(layout=...).

generate_layout_json("output/layout.json", layout_tree, ascii_preview)
generate_layout_yaml("output/layout.yaml", layout_tree, ascii_preview)

Both formats support the same wrapper structure:

  • layout_schema: canonical dashboard layout tree

  • _ascii_layout_preview: optional human/agent review aid

cwtwb includes seven packaged Gallery templates for common analytical structures. Recommendations use explicit requirements and return their scores, matching reasons, and penalties; they do not inspect data or silently generate charts.

from cwtwb import DashboardRequirements, recommend_gallery_templates

recommendations = recommend_gallery_templates(
    DashboardRequirements(
        primary_intent="trend",
        has_temporal_data=True,
        kpi_count=2,
        chart_count=3,
        chart_types=("Line", "Bar"),
    )
)

After calling list_worksheets, bind exact worksheet names with materialize_gallery_layout(...) or the MCP generate_gallery_layout tool. The generated result uses the same canonical DSL accepted by add_dashboard.

Calculation Safety

add_calculated_field checks identifiers used as function calls against the packaged Tableau catalog before editing XML. For example, CHR(10) is rejected with a CHAR() suggestion. This is a lightweight function-name check, not a complete Tableau parser or substitute for Tableau Cloud semantic validation.

Use validate_formula=False only when targeting a newer Tableau function that is not yet in the packaged catalog. Existing workbooks can be reviewed with audit_calculated_fields(). Repairs are separate and default to dry_run=True.

Highlights

Area

What you get

Workbook authoring

Generate .twb / .twbx files from templates or from scratch; add hierarchies, sets, rich dynamic titles, and parameter placeholders

Chart building

Build bar, line, pie, map, KPI, dual-axis, layered, and ordered multi-column table workbooks

Table calculations

Author calculation addressing metadata, domain completion, subtotals, and nested table-calculation dependencies

Dashboard actions

Add filter, highlight, URL, navigation, parameter, and set actions through Python or MCP

Safety

Validate function names and calculated-field roles, then validate structure, Tableau XSD (2026.1/2026.2), and REST API semantics before publishing

Dashboard Gallery

Rank seven explainable layouts and bind exact worksheet names into the canonical DSL

Cloud validation

REST API syntactic/semantic validation + upload to Tableau Cloud/Server with optional screenshot

Migration

Repoint existing workbooks to new data sources with explicit steps

MCP support

Drive workbook workflows from Claude, Cursor, VSCode, or other MCP clients

See It In Action

This GIF shows the MCP tool flow that builds a dashboard step by step.

Architecture

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from cwtwb.twb_editor    │  │
  │  │  tools_validate          │  │  import TWBEditor         │  │
  │  │                          │  │                           │  │
  │  │                          │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │                          │  │  editor.validate_schema() │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  │       validate_schema()  ·  save()                            │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                    Packaged References                        │
  │    empty_template.twb  ·  Superstore XLS/Hyper                │
  │    tableau_all_functions.json  ·  dataset profiles            │
  │    vendored Tableau TWB XSD schemas (2026.1 / 2026.2)         │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │               Cloud Validation (optional)                    │
  │    validate_workbook_api → REST API semantic validation      │
  │    upload_workbook       → Tableau Cloud/Server publish      │
  │    screenshot_workbook   → capture view for visual check     │
  └───────────────────────────────────────────────────────────────┘

Mermaid view:

flowchart TD
    subgraph Interfaces
        MCP["MCP Server<br/>tools_workbook<br/>tools_validate"]
        PY["Python Library<br/>TWBEditor API"]
    end

    subgraph Editor["Core Editor"]
        TWB["TWBEditor<br/>parameters · connections<br/>charts · dashboards<br/>validate_schema · save"]
    end

    subgraph Builders["Workbook Systems"]
        CHARTS["Chart Builders<br/>basic · dual-axis<br/>pie · text · map · recipes"]
        DASH["Dashboard System<br/>layouts · actions<br/>dependencies"]
        ANALYSIS["Analysis & Migration<br/>migration.py<br/>twb_analyzer.py<br/>capability_registry"]
    end

    subgraph References["Packaged References"]
        REFS["empty_template.twb<br/>Superstore XLS/Hyper<br/>Tableau functions<br/>TWB XSD schemas"]
    end

    subgraph Engine["XML Engine"]
        XML["lxml patch pipeline<br/>template.twb/.twbx → patch → validate → save"]
    end

    subgraph Outputs
        OUT["output.twb / output.twbx"]
        CLOUD["Cloud Validation<br/>REST semantic validation<br/>upload · screenshot"]
    end

    MCP --> TWB
    PY --> TWB
    TWB --> CHARTS
    TWB --> DASH
    TWB --> ANALYSIS
    CHARTS --> XML
    DASH --> XML
    ANALYSIS --> XML
    REFS --> TWB
    REFS --> XML
    XML --> OUT
    OUT --> CLOUD

The reference layer is packaged with the library so agents and scripts can start from known-good workbook assets, resolve Tableau calculation syntax, run Hyper-backed examples, and validate against local XSD schemas without relying on a checked-out repository.

Agent Architecture

cwtwb is designed for tool-using agents, not just direct Python calls. The MCP server gives agents a small, stateful workbook editing surface; skill resources give phase-specific Tableau guidance before each set of tool calls.

Human or agent prompt
        |
        v
MCP server instructions
        |
        v
Skill resources
data_quality -> governance -> synthetic_data -> design_advisor -> metric_blueprint
-> calculation_builder -> chart_builder -> dashboard_designer -> formatting
-> validation -> quality_review -> documentation
        |
        v
Workbook tools
create/open -> list_fields -> add/configure -> layout -> save -> validate/upload
        |
        v
TWB/TWBX artifact + validation evidence

Prompts explain what to build. Skills explain how to build it well. Tools make the workbook changes inspectable and repeatable.

The packaged skill architecture is documented in src/cwtwb/skills/README.md, including its workflow diagram and the boundary between guidance, explicit mutations, and validation evidence.

Capability Boundary

cwtwb keeps its public surface intentionally small:

Level

Meaning

Core

Stable primitives for normal SDK docs, examples, and MCP workflows

Advanced

Supported compositions and interaction patterns with more moving parts

Recipe

Showcase patterns exposed through configure_chart_recipe, not one tool per chart

Use list_capabilities or describe_capability when an agent needs to check whether a requested chart or workbook feature belongs in the stable surface.

Design Decisions

  • The MCP server uses a stateful session model: open or create a workbook, mutate it through explicit tools, then call save_workbook.

  • Skills are phase-specific operating guides, not generic prompt stuffing.

  • save_workbook, validate_workbook, validate_workbook_api, and upload_workbook have separate responsibilities so agents do not confuse writing, local checks, semantic validation, and publishing.

  • The capability registry keeps the product boundary explicit instead of letting showcase examples become accidental API promises.

Validation

cwtwb provides four levels of workbook validation:

Level

Description

Requires

1. Local XSD

Validate against the official Tableau TWB XSD schema (version-aware: 2026.1 or 2026.2)

None (built-in)

2. REST API Syntactic

Validate XML syntax via Tableau Cloud REST API

Tableau credentials + Tableau Cloud 2026.2+

3. REST API Semantic

Full semantic validation without publishing — default cloud check for .twb

Tableau credentials + Tableau Cloud 2026.2+

4. Upload + Screenshot

Publish to Tableau Cloud/Server and capture a view image

Tableau credentials + pip install "cwtwb[validate]"

# Level 1 — Local XSD (in-memory, no save required)
result = editor.validate_schema()
print(result.to_text())

# Level 3 — REST API semantic validation
from cwtwb.validate.uploader import TableauUploader
uploader = TableauUploader(env_path="project/.env")
result = uploader.validate("output.twb", validation_level="semantic")

# Save with local XSD validation; REST API semantic validation also runs when .env is configured
editor.save("output.twb")
# MCP tools
validate_workbook(file_path="output.twb")                                       # Local XSD validation
validate_workbook_api(twb_path="output.twb", validation_level="semantic")        # Default cloud semantic validation, no publish
validate_workbook_api(twb_path="output.twb", env_path="project/.env")            # Runtime credentials
upload_workbook(twb_path="output.twb")                                          # Publish/openability evidence or TWBX validation
screenshot_workbook(workbook_id="...", view_name="Sheet 1")                     # Visual check after upload_workbook

FAQ

What is the difference between .twb and .twbx?

.twb is the workbook XML. .twbx is the packaged version that bundles the workbook together with extracts and images.

Does validate_workbook save files?

No. validate_workbook() performs local XSD validation on the active in-memory workbook or an existing .twb / .twbx file. It does not write output. save_workbook() is the tool that writes files.

What validation does save() perform?

save() runs local XSD validation automatically before replacing the final output file. For .twb output, REST API semantic validation also runs when Tableau credentials are configured and the server supports it. Use validate_workbook_api(..., validation_level="semantic") when you want to request the Tableau Cloud/Server validation step directly.

What is upload_workbook for?

upload_workbook publishes a .twb or .twbx to Tableau Cloud/Server. Use it when you explicitly need publish/openability evidence, a workbook ID for screenshots, or .twbx package validation. For the default .twb cloud semantic check, prefer validate_workbook_api because it does not publish or store the workbook. Requires pip install "cwtwb[validate]" and Tableau credentials from environment variables, an explicit env_path, TABLEAU_ENV_FILE, or a .env file next to the workbook.

How do I set up Tableau Cloud/Server validation?

  1. Install: pip install "cwtwb[validate]"

  2. Copy .env.example to .env

  3. Fill in your Tableau Cloud/Server PAT credentials

  4. Call save_workbook to write the .twb or .twbx

  5. Call validate_workbook_api for the default REST API semantic validation, or upload_workbook only when you also want publish/openability evidence, screenshots, or .twbx validation

Credential lookup order is explicit env_path first, then environment variables, TABLEAU_ENV_FILE, the workbook sibling .env, the current working directory .env, the cwtwb project .env, and finally the user's home .env. Prefer env_path for one-off MCP calls instead of editing MCP server configuration and restarting the server.

If validation reports that tableauserverclient is missing, call get_mcp_status first. It reports the MCP process's Python executable, cwtwb version, and whether the Tableau client is importable without exposing credentials. An env_path change is runtime-scoped and does not require an MCP restart; installing dependencies into a different Python environment does not fix the running server, so install the validation extra into the interpreter reported by get_mcp_status and reconnect only when the runtime or tool schema changes.

When should I use uvx cwtwb versus python -m cwtwb.mcp_server?

Use uvx cwtwb for the normal MCP workflow. Use python -m cwtwb.mcp_server for local testing without uvx.

For backward compatibility, uvx --from cwtwb cwtwb-mcp, python -m cwtwb.server, and python -m cwtwb.mcp continue to work.

Where is the full guide?

See the online guide.

Documentation

Available Tools

84 tools
add_calculated_fieldC

Add a calculated field to the datasource.

For formula syntax and best practices, read: read_resource('cwtwb://skills/calculation_builder')

Inputs: formula (required), field_name (required), role, datatype, +5 more. Returns: result

add_combined_setC

Union existing native sets at the same dimension grain.

Inputs: set_name (required), set_names (required). Returns: result

add_dashboardA

Create a dashboard combining multiple worksheets.

Recommended workflow for complex dashboards:

  1. Call list_worksheets to lock worksheet names

  2. Design layout with the user (KPI row, main chart, detail views, filters)

  3. Call generate_layout_json to save the layout as a JSON or YAML file

  4. Call add_dashboard with layout=<layout_file_path>

Layout options:

  • str (file path): Path to JSON or YAML layout file (recommended for complex layouts)

  • dict: Custom declarative layout tree passed inline Native set control (mode dropdown or checkdropdown): {"type": "set_control", "field": "Set name", "worksheet": "View", "mode": "dropdown"}

  • "auto" (default): Simple vertical fallback — use layout dict or layout file for mixed layouts

  • "vertical": All worksheets stacked vertically

  • "horizontal": All worksheets side-by-side

  • "grid-2x2": 2x2 grid layout

For dashboard design best practices, read: read_resource('cwtwb://skills/dashboard_designer')

Inputs: dashboard_name (required), worksheet_names (required), width, height, +1 more. Returns: result

add_dashboard_actionC

Add a filter, highlight, URL, navigation, or parameter dashboard action.

For action_type="parameter", provide source_field, target_parameter, and a Tableau-serialized clear_value such as d:2026-02-12, i:0, or s:LROOT:All.

Inputs: action_type (required), dashboard_name (required), url, fields, +13 more. Returns: result

add_dashboard_extensionC

Add a native dashboard extension with structured manifest and settings.

Inputs: manifest (required), dashboard_name (required), x, y, +3 more. Returns: result

add_dashboard_set_actionB

Add a Set Action (edit-group-action) to a dashboard.

The set fills with the marks under the pointer and clears when it leaves, enabling hover-driven labels and calculations.

Inputs: target_set (required), source_sheet (required), dashboard_name (required), caption, +4 more. Returns: result

add_dashboard_toggle_buttonC

Show/hide a dedicated dashboard sheet container with a native button.

Inputs: dashboard_name (required), position, caption_shown, caption_hidden, +3 more. Returns: result

add_groupC

Create a categorical dimension by grouping source-field members.

Inputs: groups (required), field_name (required), source_field (required), default_value, +1 more. Returns: result

add_hierarchyC

Create an ordered Tableau drill hierarchy from bare dimension fields.

Inputs: name (required), fields (required). Returns: result

add_hyper_datasourceC

Add and activate another independent extracted data source.

Inputs: name (required), filepath (required), table_name. Returns: result

add_parameterC

Add a parameter to the workbook.

Inputs: name (required), alias, datatype, max_value, +8 more. Returns: result

add_percentage_bandC

Add a native percentage distribution band on an existing axis.

Inputs: axis_field (required), worksheet_name (required), scope, formula, +7 more. Returns: result

add_reference_bandC

Add a constant or field-backed native filled band on an existing axis.

Inputs: axis_field (required), worksheet_name (required), scope, fill_color, +9 more. Returns: result

add_reference_lineC

Add a field-backed reference line to a configured worksheet pane.

Inputs: axis_field (required), value_field (required), worksheet_name (required), label, +6 more. Returns: result

add_setB

Create a Tableau set (datasource filter-group) for membership logic.

Use basis_field + top_n to build a top-N set (e.g. Top Central ranked by SUM(Central - Qty)); omit both to create an empty set used as a Set Action target (e.g. Highlighted Manufacturer).

Inputs: set_name (required), dimension_field (required), top_n, members, +5 more. Returns: result

add_worksheetC

Add a new blank worksheet to the workbook.

Inputs: worksheet_name (required). Returns: result

analyze_twbA

Analyze an existing TWB/TWBX file against cwtwb's declared capabilities.

This tool requires a file_path that already exists on disk. It cannot analyze the active in-memory workbook directly and it does not save the current workbook. For a newly generated workbook, call save_workbook first, then pass that saved path to analyze_twb.

Inputs: file_path (required). Returns: result

apply_twb_migrationC

Apply a workbook migration and write a migrated TWB plus reports.

Inputs: file_path (required), output_path (required), target_source (required), scope, +1 more. Returns: result

apply_worksheet_refactorB

Rewrite one worksheet to use replacement fields without touching others.

Inputs: replacements (required), worksheet_name (required). Returns: result

audit_calculated_fieldsA

Report calculated-field datatype/role contradictions without mutation.

Inputs: no named parameters. Returns: result

clone_worksheetC

Clone an existing worksheet and its worksheet window.

Inputs: source_worksheet (required), target_worksheet (required). Returns: result

configure_chartC

Configure chart type and field mappings for a worksheet.

For chart type selection and encoding best practices, read: read_resource('cwtwb://skills/chart_builder')

Inputs: worksheet_name (required), rows, size, color, +23 more. Returns: result

configure_chart_recipeC

Configure a showcase recipe chart through the shared recipe registry.

For recipe chart patterns, read: read_resource('cwtwb://skills/chart_builder')

Inputs: recipe_name (required), worksheet_name (required), recipe_args, auto_ensure_prerequisites. Returns: result

configure_custom_labelC

Set rich literal/field mark labels while preserving pane calculation context.

Inputs: runs (required), worksheet_name (required), pane_index. Returns: result

configure_custom_tooltipD

Set formatted text/field runs or embedded sheets with explicit filter_fields.

Inputs: runs (required), worksheet_name (required), pane_index. Returns: result

configure_datasource_blendC

Link independently aggregated sources in a worksheet without a join.

Inputs: link_fields (required), worksheet_name (required), secondary_fields (required), secondary_datasource (required). Returns: result

configure_dual_axisC

Configure a dual-axis chart composition.

For dual-axis chart patterns and best practices, read: read_resource('cwtwb://skills/chart_builder')

Inputs: worksheet_name (required), rows, size_1, size_2, +27 more. Returns: result

configure_layered_chartC

Build layered panes with encodings, ordered values and native styles.

sort_mode='computed' orders dimension members before table calculations; 'shelf' explicitly selects shelf sorting, and 'auto' retains default routing. table_calc_context gives explicit overrides a local native instance identity, including map calculations whose dimensions live on mark detail shelves.

Inputs: worksheet_name (required), rows, panes, columns, +10 more. Returns: result

configure_subtotalsC

Configure visual subtotals and per-dimension subtotal labels.

Inputs: measure_fields (required), worksheet_name (required), label, aggregation, +1 more. Returns: result

configure_worksheet_domain_rangeC

Complete missing dates for discrete exact-date fields; [] disables completion.

Inputs: fields (required), worksheet_name (required). Returns: result

configure_worksheet_styleC

Apply worksheet-level styling: background color, axis/grid/border visibility.

pane_mark_style accepts mark-labels-range-field as a public field expression and resolves its native qualified reference for min/max labels.

For formatting best practices, read: read_resource('cwtwb://skills/formatting')

Inputs: worksheet_name (required), hide_axes, map_style, axis_style, +25 more. Returns: result

configure_worksheet_time_seriesC

Extend a continuous date domain and allow calculations on added periods.

Inputs: field (required), periods (required), worksheet_name (required), period_type, +1 more. Returns: result

convert_workbookA

Convert TWB, TWBX, YAML or JSON by output suffix without an editor session.

YAML/JSON contain an editable native XML tree, not a simplified chart DSL. Assets are copied alongside definitions; keep these files together. Unknown XML is retained. Only XML syntax is checked, not Tableau runtime behavior. The current editor session is not modified. Existing output requires force.

Inputs: input_path (required), output_path (required), force.

copy_default_device_layoutC

Preserve default geometry in a custom Phone/Tablet layout with shared IDs.

Inputs: dashboard_name (required), device_name. Returns: result

create_workbookC

Create a new workbook from a TWB or TWBX template file.

Inputs: template_path, workbook_name. Returns: result

describe_capabilityB

Describe one declared capability and its support tier.

Inputs: kind (required), name (required). Returns: result

diff_template_gapC

Summarize the non-core capability gap of a TWB template.

Inputs: file_path (required). Returns: result

enable_automatic_phone_layoutC

Derive a scrolling Phone layout from the default dashboard objects.

Inputs: dashboard_name (required), worksheet_height. Returns: result

enable_domain_completionC

Add an INDEX() detail table calculation to trigger Tableau densification.

Inputs: worksheet_name (required), field_name, ordering_type. Returns: result

generate_layout_jsonA

Generate and save a dashboard layout file.

Recommended workflow:

  1. Call list_worksheets to get available worksheet names

  2. Design the layout with the user (show ASCII preview for confirmation)

  3. Call this tool to save the layout as a JSON or YAML file

  4. Call add_dashboard with layout=<this_file_path>

The layout_tree uses the declarative container DSL:

  • {"type": "container", "direction": "vertical"|"horizontal", "children": [...]}

  • {"type": "worksheet", "name": "<worksheet_name>"}

  • Use "fixed_size" (int, pixels) for KPI rows and filter sidebars

  • Use "weight" (int, relative) for main analytical areas

Inputs: layout_tree (required), output_path (required), ascii_preview (required). Returns: result

generate_layout_yamlA

Generate and save a dashboard layout YAML file.

Recommended workflow:

  1. Call list_worksheets to get available worksheet names

  2. Design the layout with the user (show ASCII preview for confirmation)

  3. Call this tool to save the layout as a YAML file

  4. Call add_dashboard with layout=<this_file_path>

The layout_tree uses the same declarative container DSL as generate_layout_json.

Inputs: layout_tree (required), output_path (required), ascii_preview (required). Returns: result

get_mcp_statusA

Report cwtwb MCP server version, workbook state, and safe usage guardrails.

Use this when an AI client seems stale, cannot see expected tools, or is about to edit MCP configuration to switch Tableau credentials. This tool never returns secret values.

Inputs: no named parameters.

import_blended_fieldC

Define a primary aggregate proxy for a secondary source field.

Inputs: alias (required), field (required), secondary_datasource (required). Returns: result

initialize_dashboard_filter_actionC

Initialize an existing native filter action's targets with overridable members.

Inputs: members (required), action_name (required), dashboard_name (required). Returns: result

inspect_excel_connectionC

Preview how an Excel workbook will be interpreted before connection setup.

Inputs: file_path (required), sheet_name. Returns: result

inspect_target_schemaB

Inspect the first-sheet schema of a target Excel datasource.

Inputs: target_source (required). Returns: result

list_capabilitiesA

List cwtwb's declared capability boundary.

This reports what workbook features/charts are supported by cwtwb. It does not enumerate callable MCP tools and should not be used to infer whether a tool like add_dashboard or save_workbook exists.

Inputs: no named parameters. Returns: result

list_dashboardsA

List dashboards and their worksheet zones in the current workbook.

Inputs: no named parameters. Returns: result

list_fieldsA

List all available fields in the current workbook datasource.

Inputs: no named parameters. Returns: result

list_worksheetsA

List worksheet names in the current workbook.

Inputs: no named parameters. Returns: result

open_workbookA

Open an existing workbook (.twb or .twbx) for in-place worksheet editing.

Inputs: file_path (required). Returns: result

preview_twb_migrationC

Preview a workbook migration onto a target datasource.

Inputs: file_path (required), target_source (required), scope, mapping_overrides. Returns: result

preview_worksheet_refactorB

Preview worksheet-scoped field rewrites without mutating the workbook.

Inputs: replacements (required), worksheet_name (required). Returns: result

profile_twb_for_migrationB

Profile workbook datasources and worksheet scope before migration.

Inputs: file_path (required), scope, target_source. Returns: result

propose_field_mappingC

Scan source and target schema and propose a field mapping.

Inputs: file_path (required), target_source (required), scope, mapping_overrides. Returns: result

remove_calculated_fieldA

Remove a previously added calculated field.

Inputs: field_name (required). Returns: result

repair_calculated_field_issuesB

Preview or explicitly apply selected calculated-field metadata repairs.

Inputs: dry_run, field_names, issue_codes, datasource_names. Returns: result

save_workbookA

Save the active workbook as a .twb or .twbx file. Use a .twbx extension to produce a packaged workbook (ZIP) that bundles the XML with any data extracts and images carried over from the source .twbx.

This is the only default MCP tool that writes the active in-memory workbook to disk. After create_workbook/open_workbook plus worksheet/chart/dashboard edits, call save_workbook with the desired output_path to create the final .twb or .twbx file. validate_workbook and analyze_twb do not save files.

Inputs: output_path (required). Returns: result

screenshot_workbookA

Screenshot a published workbook's view for human review.

Use after upload_workbook to capture a visual snapshot. The screenshot is saved locally for human inspection.

Args: workbook_id: The workbook ID returned by upload_workbook. output_dir: Directory to save screenshot (default: output/validation). view_index: Index of the view to screenshot (default: 0). view_name: Name of the view to screenshot (overrides view_index). env_path: Optional path to a .env file with Tableau credentials. Explicit env_path takes priority over process environment variables.

Returns: {success, path, view_name, view_id, size_kb, error}

Inputs: workbook_id (required), env_path, view_name, output_dir, +1 more.

select_datasourceC

Select the source for subsequent field and worksheet authoring.

Inputs: name (required). Returns: result

set_compound_color_paletteC

Map ordered categorical tuples to colors, including Measure Names.

Inputs: fields (required), mappings (required). Returns: result

set_csv_connectionC

Configure the workbook datasource to use a local CSV connection.

Inputs: filepath (required), fields, charset, delimiter. Returns: result

set_date_optionsC

Set datasource weekday origin for date-part headers and week calculations.

Inputs: start_of_week. Returns: result

set_excel_connectionC

Configure the workbook datasource to use a local Excel connection.

Inputs: filepath (required), fields, sheet_name. Returns: result

set_field_fiscal_year_startC

Set the native fiscal year starting month on a date field and dependencies.

Inputs: field (required), month (required). Returns: result

set_field_formatC

Set or clear a field's default Tableau display format.

Inputs: field (required), default_format (required). Returns: result

set_field_geographic_roleC

Assign or clear a field's geographic role.

Inputs: field (required), geographic_role (required). Returns: result

set_geocoding_contextC

Set geographic lookup context for generated map coordinates.

Inputs: country (required), state. Returns: result

set_hyper_connectionC

Configure the workbook datasource to use a local Hyper extract connection.

Inputs: filepath (required), tables, table_name, relationships. Returns: result

set_measure_name_aliasesC

Alias actual Measure Names members, including table calculation measures.

Inputs: mapping (required), worksheet_name (required). Returns: result

set_mysql_connectionC

Configure the workbook datasource to use a local MySQL connection.

Inputs: dbname (required), server (required), username (required), table_name (required), +1 more. Returns: result

set_shape_paletteC

Embed local shape assets and map categorical members to the native palette.

Inputs: field (required), shapes (required), palette. Returns: result

set_tableauserver_connectionA

Configure the workbook datasource to use a Tableau Server connection.

This edits the workbook datasource connection only. It does not configure Tableau REST API/PAT credentials for validate_workbook_api, upload_workbook, or screenshot_workbook; pass env_path to those validation tools instead.

Inputs: dbname (required), server (required), username (required), table_name (required), +2 more. Returns: result

set_worksheet_captionB

Set or clear a plain-text worksheet caption.

Inputs: caption (required), worksheet_name (required). Returns: result

set_worksheet_hiddenB

Hide or unhide a worksheet tab by updating worksheet window metadata.

Inputs: worksheet_name (required), hidden. Returns: result

set_worksheet_titleC

Set or clear the visible plain-text worksheet title.

Inputs: title (required), worksheet_name (required). Returns: result

upload_workbookA

Publish a .twb/.twbx to Tableau Cloud for openability or screenshots.

Prefer validate_workbook_api for the default cloud semantic validation path because it does not publish or store the workbook. Use upload_workbook only when you explicitly need a published workbook_id, visual screenshot, TWBX packaging validation, or publish/openability evidence.

Args: twb_path: Path to .twb or .twbx file. data_path: Optional data file (.xlsx/.xls/.hyper) to package. name: Workbook name on Tableau Cloud (defaults to filename stem). overwrite: Whether to overwrite existing workbook with same name. env_path: Optional path to a .env file with Tableau credentials. Explicit env_path takes priority over process environment variables.

Returns: {success, workbook_id, workbook_url, views, twbx_path, twbx_size_kb, error}

Inputs: twb_path (required), name, env_path, data_path, +1 more.

validate_formulaC

Check Tableau function names without mutating the active workbook.

Inputs: formula (required), field_name. Returns: result

validate_workbookA

Validate a workbook against the official Tableau TWB XSD schema.

Checks whether the generated XML conforms to Tableau's published schema. This tool does not save or export the active workbook. If file_path is omitted, it validates the current in-memory workbook before save; if file_path is provided, it validates an existing .twb/.twbx file on disk. Call save_workbook when you need to write the workbook to a file.

Args: file_path: Path to a .twb or .twbx file to validate. If omitted, validates the currently open workbook (in memory, before save).

Returns: PASS/FAIL summary with error details.

Inputs: file_path. Returns: result

validate_workbook_apiA

Validate a .twb file via Tableau Cloud REST API (no publish).

This performs semantic validation that checks whether the workbook will actually open in Tableau — beyond what local XSD schema validation can detect (calculated field formulas, field references, data source connectivity, etc.). The file is NOT stored on the server.

Only .twb files are supported. For .twbx files, use upload_workbook.

Requires Tableau Cloud June 2026+ / Server 2026.2+ (API version 3.29+).

Args: twb_path: Path to .twb file. validation_level: "syntactic" (XSD only) or "semantic" (full, default). env_path: Optional path to a .env file with Tableau credentials. Explicit env_path takes priority over process environment variables.

Returns: {success, validation_level, valid, errors, warnings, error}

Inputs: twb_path (required), env_path, validation_level.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.8/5.0

    Scored across 84 tools

    Disambiguation3/5

    Many tools are distinct and descriptions disambiguate, but several clusters overlap: multiple validate/analyze tools, several configure_chart variants, and duplicate layout generators (JSON vs YAML) make selection uncertain. The agent can usually recover from descriptions, but not all boundaries are crisp.

    Naming Consistency5/5

    All names use snake_case with a consistent verb_noun or verb_noun_phrase pattern (add_, set_, configure_, list_, validate_, etc.). No mixed conventions or cryptic abbreviations appear in tool names.

    Tool Count1/5

    84 tools is an extreme over-scoping for a single MCP server; the rubric treats 50+ as an extreme mismatch. Even with a broad Tableau authoring domain, this volume imposes heavy selection and maintenance burden.

    Completeness4/5

    The surface covers workbook lifecycle, worksheets, dashboards, fields, calculations, connections, migration, validation, and publishing. Some deletion/removal operations (e.g., dashboards, worksheets, parameters) are absent, but most authoring workflows are covered.

    Maintenance

    ActivityActive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI applications to integrate with Tableau through tools, resources, and prompts for querying data, exploring content, and retrieving visualizations from Tableau workbooks and datasources.
      36,168 npm
      378
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables integration with Tableau to query data, explore workbook content, and retrieve visualization images through natural language. It provides developer primitives for building AI applications that interact seamlessly with Tableau servers.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI applications to interact with Tableau through tools for querying data, exploring content, and retrieving views.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI applications to interact with Tableau for querying data, exploring content, and retrieving views through natural language.
      Apache 2.0