cwtwb
cwtwb is an MCP server for engineering Tableau workbooks — building, editing, validating, migrating, and publishing reproducible .twb / .twbx files through stateful tool calls.
Workbook lifecycle: create from template, open existing, save as
.twb/.twbx, and convert between TWB, TWBX, YAML, and JSON (convert_workbook).Inspection: list fields, worksheets, and dashboards; check server status; browse declared capabilities via
list_capabilities/describe_capability.Data connections: configure MySQL, Tableau Server, Excel, CSV, or Hyper sources; add independent Hyper extracts; select active datasource; blend sources; preview Excel/schema interpretation.
Fields & calculations: add/remove/audit/repair calculated fields, validate formulas, create groups, sets (including top-N and combined), hierarchies, and parameters; set formats, geographic roles, fiscal year start, and date options.
Chart building: configure standard charts, dual-axis, layered panes, and showcase recipes; add reference lines, bands, and percentage bands; apply labels, tooltips, palettes, and worksheet styling; hide/caption/title/clone worksheets; preview and apply worksheet field refactors.
Dashboards: build dashboards with auto, grid, or declarative JSON/YAML layouts; bind Gallery templates via recommendations; add filter/highlight/URL/navigation/parameter/set actions; add extensions, toggle buttons, and phone/tablet device layouts.
Validation & publishing: local XSD schema checks, Tableau Cloud REST semantic validation, upload to Cloud/Server, and view screenshots for visual review.
Analysis & migration: analyze workbooks against capability boundaries, diff template gaps, profile datasources, propose field mappings, and preview/apply migrations to a new data source.
Non-mutating helpers: preview refactors, dry-run repairs, run migrations previews, and validate formulas without touching the active workbook.
Allows inspecting .hyper file schemas, resolving physical table names, and using Hyper as a datasource for guided workbook authoring.
The cwtwb package is distributed via PyPI for installation with pip.
The toolkit is a Python library and MCP server that allows programmatic generation of Tableau workbooks using Python code.
Provides XML engine (lxml) for patching, validating, and saving Tableau workbook XML files.
cwtwb
Tableau workbook engineering for reproducible
.twb/.twbxgeneration, 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>
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).
Star History
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 cwtwbTo use the stable channel instead:
pip install cwtwbIf 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 cwtwbThe 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 cwtwbFor 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_serverUse 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.yamlCommon 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.twbUse --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.twbcwtwb 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.jsonCompatibility 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
Explainable Dashboard Gallery
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 |
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 --> CLOUDThe 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 evidencePrompts 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 |
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, andupload_workbookhave 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 | Tableau credentials + Tableau Cloud 2026.2+ |
4. Upload + Screenshot | Publish to Tableau Cloud/Server and capture a view image | Tableau credentials + |
# 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_workbookFAQ
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?
Install:
pip install "cwtwb[validate]"Copy
.env.exampleto.envFill in your Tableau Cloud/Server PAT credentials
Call
save_workbookto write the.twbor.twbxCall
validate_workbook_apifor the default REST API semantic validation, orupload_workbookonly when you also want publish/openability evidence, screenshots, or.twbxvalidation
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 toolsadd_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:
Call list_worksheets to lock worksheet names
Design layout with the user (KPI row, main chart, detail views, filters)
Call generate_layout_json to save the layout as a JSON or YAML file
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_gallery_layoutC
Bind exact worksheet names to a Gallery template and validate the layout DSL.
Inputs: template_name (required), worksheet_slots (required), output_path. Returns: result
generate_layout_jsonA
Generate and save a dashboard layout file.
Recommended workflow:
Call list_worksheets to get available worksheet names
Design the layout with the user (show ASCII preview for confirmation)
Call this tool to save the layout as a JSON or YAML file
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:
Call list_worksheets to get available worksheet names
Design the layout with the user (show ASCII preview for confirmation)
Call this tool to save the layout as a YAML file
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
link_worksheet_filtersC
Link matching categorical filters so one control filters all given sheets.
Inputs: field (required), worksheet_names (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_gallery_templatesA
List packaged Gallery layouts and their explicit worksheet slots.
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
recommend_gallery_templatesC
Recommend compatible Gallery templates with scores and reasons.
Inputs: limit, kpi_count, chart_count, chart_types, +4 more. 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_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
Scored across 84 tools
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.
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.
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.
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
Related MCP Connectors
AI data analyst: ask about your Excel, CSV, GA4 or database data and get charts and dashboards back
Clean messy tabular data and render publication-ready PNG charts from your AI assistant.
Charts and dashboards as images for AI agents. No browser, same data same bytes. Local and free.
AI data analyst by getdot.ai. Ask your data warehouse in plain English; get SQL, answers and charts.
Related MCP Servers
AlicenseNot gradedqualityBmaintenanceEnables 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 npm378Apache 2.0- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables AI applications to interact with Tableau through tools for querying data, exploring content, and retrieving views.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI applications to interact with Tableau for querying data, exploring content, and retrieving views through natural language.Apache 2.0