cwtwb

cwtwb

Tableau Workbook (.twb/.twbx) generation toolkit for reproducible dashboards and workbook engineeringProgrammatically create Tableau workbooks with stable analytical primitives, dashboard composition, and built-in structural validation.

Author: Cooper Wenhua <[email protected]>

Overview

cwtwb is a Model Context Protocol (MCP) server and Python toolkit for generating Tableau Desktop workbook files (.twb / .twbx) from code or AI-driven tool calls.

It is designed as a workbook engineering layer, not as a conversational data exploration agent. The goal is to make workbook generation reproducible, inspectable, and safe to automate in local workflows, scripts, and CI.

The default workflow is:

1. Start from a known template (.twb or .twbx) or the built-in zero-config template
2. Add calculated fields and parameters
3. Build worksheets from stable chart primitives
4. Assemble dashboards and interactions
5. Save and validate a .twb or .twbx that opens in Tableau Desktop

For natural-language MCP authoring, cwtwb also supports a guided run workflowthat starts from a real datasource file instead of a hand-written contract:

1. Start an authoring run from a local Excel or Hyper file
2. Inspect the datasource schema and pause for human confirmation
3. Build an analysis brief, present 2-4 candidate dashboard directions, and confirm the chosen direction
4. Draft, review, and finalize a structured authoring contract
5. Build and confirm a human-facing wireframe
6. Build a mechanical execution plan internally and generate the final workbook
7. Persist every intermediate artifact under tmp/agentic_run/{run_id}/

                            Interfaces
  ┌───────────────────────────────────────────────────────────────┐
  │  ┌──────────────────────────┐  ┌───────────────────────────┐  │
  │  │        MCP Server        │  │      Python Library       │  │
  │  │  tools_workbook          │  │  from cwtwb.twb_editor    │  │
  │  │  tools_layout            │  │  import TWBEditor         │  │
  │  │  tools_migration         │  │                           │  │
  │  │  tools_support           │  │  editor.add_...()         │  │
  │  │                          │  │  editor.configure_...()   │  │
  │  │  (Claude / Cursor /      │  │  editor.save(...)         │  │
  │  │   VSCode / Claude Code)  │  │                           │  │
  │  └─────────────┬────────────┘  └──────────────┬────────────┘  │
  │                └──────────────┬────────────────┘               │
  └─────────────────────────────  ┼  ─────────────────────────────┘
                                  ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                          TWBEditor                            │
  │       ParametersMixin  ·  ConnectionsMixin                    │
  │       ChartsMixin      ·  DashboardsMixin                     │
  └──────────┬──────────────────┬──────────────────┬─────────────┘
             ▼                  ▼                  ▼
  ┌──────────────────┐  ┌──────────────┐  ┌──────────────────────┐
  │  Chart Builders  │  │  Dashboard   │  │  Analysis &          │
  │                  │  │  System      │  │  Migration           │
  │  Basic  DualAxis │  │              │  │                      │
  │  Pie    Text     │  │  layouts     │  │  migration.py        │
  │  Map    Recipes  │  │  actions     │  │  twb_analyzer.py     │
  │                  │  │  dependencies│  │  capability_registry │
  └────────┬─────────┘  └──────┬───────┘  └──────────┬───────────┘
           └───────────────────┼──────────────────────┘
                               ▼
  ┌───────────────────────────────────────────────────────────────┐
  │                     XML Engine  (lxml)                        │
  │    template.twb/.twbx  →  patch  →  validate  →  save        │
  └───────────────────────────────┬───────────────────────────────┘
                                  ▼
                      output.twb  /  output.twbx

Installation

pip install cwtwb

To run the bundled Hyper-backed example that inspects .hyper files andresolves the physical Orders_* table automatically, install the optionalexample dependency as well:

pip install "cwtwb[examples]"

Requirements

• Python >= 3.10
• lxml >= 5.0
• uv
• mcp >= 1.0

Quick Start

As MCP Server

To allow an MCP client to build Tableau workbooks automatically, add cwtwbto that client's MCP configuration.

The launch command is the same across clients:

uvx cwtwb

Each client stores this command in a different configuration format. Use thematching example below.

Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows and add:

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

Cursor IDE

1. Open Cursor Settings -> Features -> MCP
2. Click Add New MCP Server
3. Set Type to command
4. Set Name to cwtwb
5. Set Command to uvx cwtwb

Claude Code

claude mcp add cwtwb -- uvx cwtwb

VSCode

Open the workspace .vscode/mcp.json file or your user-profile mcp.jsonfile and add:

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

In VSCode, you can open these files from the Command Palette withMCP: Open Workspace Folder Configuration orMCP: Open User Configuration. You can also use MCP: Add Server andenter the same uvx cwtwb command through the guided flow.

For local testing without uvx, you can also start the server with:

python -m cwtwb.mcp

As Python Library

Use TWBEditor(...) to start from a template and rebuild workbook content.Use TWBEditor.open_existing(...) when you want to keep existing worksheetsand dashboards and reconfigure a sheet in place.

from cwtwb.twb_editor import TWBEditor

editor = TWBEditor("")  # "" uses the built-in Superstore template
editor.clear_worksheets()
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")

editor.add_worksheet("Sales by Category")
editor.configure_chart(
    worksheet_name="Sales by Category",
    mark_type="Bar",
    rows=["Category"],
    columns=["SUM(Sales)"],
)

editor.add_worksheet("Segment Pie")
editor.configure_chart(
    worksheet_name="Segment Pie",
    mark_type="Pie",
    color="Segment",
    wedge_size="SUM(Sales)",
)

editor.add_dashboard(
    dashboard_name="Overview",
    worksheet_names=["Sales by Category", "Segment Pie"],
    layout="horizontal",
)

editor.save("output/my_workbook.twb")

Clone and Refactor an Existing Worksheet

Use worksheet clone/refactor when you want to duplicate an existing visualmodule and rebind only the cloned worksheet to a different core measure. Thisis especially useful for KPI cards such as turning a Sales KPI worksheet intoan independent Profit KPI worksheet while preserving the original sheet.

from cwtwb.twb_editor import TWBEditor

editor = TWBEditor.open_existing("examples/worksheet_refactor_kpi_profit/5 KPI Design Ideas (2).twb")

editor.clone_worksheet("1. KPI", "1. KPI Profit")
editor.apply_worksheet_refactor("1. KPI Profit", {"Sales": "Profit"})
editor.set_worksheet_hidden("1. KPI Profit", hidden=False)

editor.save("output/kpi_profit_clone.twb")

Available worksheet-refactor helpers:

• clone_worksheet(source_worksheet, target_worksheet)
• preview_worksheet_refactor(worksheet_name, replacements)
• apply_worksheet_refactor(worksheet_name, replacements)
• set_worksheet_hidden(worksheet_name, hidden=True)

apply_worksheet_refactor(...) now also performs a worksheet-local identitynormalization pass for generic Tableau Calculation_* fields. This stabilizespill labels after clone-and-replace workflows and returns post_processevidence describing renamed calculation identities and worksheet-local rewritemaps.

Working with Packaged Workbooks (.twbx)

.twbx files are ZIP archives that bundle the workbook XML together with data extracts (.hyper) and image assets. cwtwb reads and writes them transparently:

from cwtwb.twb_editor import TWBEditor

# Open a packaged workbook — extracts and images are preserved automatically
editor = TWBEditor.open_existing("templates/dashboard/MyDashboard.twbx")

# Make changes as usual
editor.add_calculated_field("Profit Ratio", "SUM([Profit])/SUM([Sales])")

# Save as .twbx — re-bundles the updated .twb with the original extracts/images
editor.save("output/MyDashboard_v2.twbx")

# Or extract just the XML when the packaged format isn't needed
editor.save("output/MyDashboard_v2.twb")

A plain .twb can also be packaged:

editor = TWBEditor("templates/twb/superstore.twb")
# ...
editor.save("output/superstore.twbx")  # produces a single-entry ZIP with the .twb inside

MCP Tools

MCP Prompts

The MCP server also exposes prompts that guide a datasource-first, human-in-the-loop workflow:

Guided MCP Authoring Runs

Use the guided run flow when you want a more structured Agentic BI authoring experience than a single free-form tool sequence.

High-level flow:

1. start_authoring_run(datasource_path=...)
2. intake_datasource_schema(run_id)
3. Human confirms the schema, preferably with interactive_stage_confirmation(..., stage="schema")
4. build_analysis_brief(...)
5. In agent_first mode, author and present 2-4 candidate directions, then finalize_analysis_brief(...)
6. Human confirms the selected direction, preferably with interactive_stage_confirmation(..., stage="analysis")
7. draft_authoring_contract(...)
8. review_authoring_contract_for_run(...)
9. finalize_authoring_contract(...)
10. Human confirms the contract, preferably with interactive_stage_confirmation(..., stage="contract")
11. build_wireframe(...)
12. finalize_wireframe(...)
13. Human confirms the wireframe, preferably with interactive_stage_confirmation(..., stage="wireframe")
14. build_execution_plan(...)
15. generate_workbook_from_run(...)

confirm_authoring_stage(...) is still the persistence step when a client fallsback to chat or when replaying an already-explicit human decision. By default,execution_plan remains an internal artifact and is not a human approval gate.

Every run writes versioned artifacts, for example:

tmp/agentic_run/20260319-153045-a1b2c3d4/manifest.json
tmp/agentic_run/20260319-153045-a1b2c3d4/schema_summary.20260319-153046.json
tmp/agentic_run/20260319-153045-a1b2c3d4/contract_final.20260319-153120.json
tmp/agentic_run/20260319-153045-a1b2c3d4/execution_plan.20260319-153155.json
tmp/agentic_run/20260319-153045-a1b2c3d4/final_workbook.twb
tmp/agentic_run/20260319-153045-a1b2c3d4/validation_report.20260319-153205.json
tmp/agentic_run/20260319-153045-a1b2c3d4/analysis_report.20260319-153206.json

Supported datasource types for this workflow today:

• Excel (.xls, .xlsx, .xlsm)
• Hyper (.hyper)

Capability Model

Core primitives

These are the stable building blocks the project should continue to promise:

• Bar
• Line
• Area
• Pie
• Map
• Text / KPI cards
• Parameters and calculated fields
• Basic dashboard composition

Advanced patterns

These are supported, but they are higher-level compositions or interaction features rather than the default surface area:

• Scatterplot
• Heatmap
• Tree Map
• Bubble Chart
• Dual Axis — mark_color_1/2, color_map_1, reverse_axis_1, hide_zeroline, synchronized
• Table Calculations — RANK_DENSE, RUNNING_SUM, WINDOW_SUM via add_calculated_field(table_calc="Rows")
• KPI Difference badges — MIN(1) dummy axis + axis_fixed_range + color_map + customized_label
• Donut (via extra_axes) — multi-pane Pie + white circle using configure_dual_axis(extra_axes=[...]); supports color_map for :Measure Names palette
• Rich-text labels — configure_chart(label_runs=[...]) for multi-style KPI cards and dynamic titles with inline field values
• Advanced worksheet styling — configure_worksheet_style supports pane-level cell/datalabel/mark styles, per-field label/cell/header formats, axis tick control, tooltip disabling, and all Tableau visual noise suppressions
• Row dimension header suppression — configure_worksheet_style(hide_row_label="FieldName")
• Filter zones, parameter controls, color legends
• Dashboard filter, highlight, URL, and go-to-sheet actions
• Worksheet captions
• Declarative JSON layout workflows
• Dashboard zone title control via show_title: false in layout dicts

Recipes and showcase patterns

These can be generated today, but they should be treated as recipes or examples rather than first-class promises:

• Donut
• Lollipop
• Bullet
• Bump
• Butterfly
• Calendar

Recipe charts are intentionally exposed through a single configure_chart_recipetool so the public MCP surface does not grow one tool at a time for everyshowcase pattern.

This distinction matters because cwtwb is not trying to become a chart zoo or compete with Tableau's own conversational analysis tooling. The project is strongest when it provides a reliable, automatable workbook generation layer.

Capability-first workflow

When you are not sure whether something belongs in the stable SDK surface:

1. Use list_capabilities to inspect the declared boundary
2. Use describe_capability to check a specific chart, encoding, or feature
3. Use analyze_twb or diff_template_gap before chasing a showcase template

This keeps new feature work aligned with the project's real product boundary instead of with whatever happens to appear in a sample workbook.

Built-in Validation

Structural validation

save() automatically validates the TWB XML structure before writing:

• Fatal errors such as missing <workbook> or <datasources> raise TWBValidationError
• Warnings such as missing <view> or <panes> are logged but do not block saving
• Validation can be disabled with editor.save("output.twb", validate=False) or editor.save("output.twbx", validate=False)

XSD schema validation

TWBEditor.validate_schema() checks the workbook against the official Tableau TWB XSD schema (2026.1), vendored at vendor/tableau-document-schemas/:

result = editor.validate_schema()
print(result.to_text())
# PASS  Workbook is valid against Tableau TWB XSD schema (2026.1)
# — or —
# FAIL  Schema validation failed (2 error(s)):
#   * Element 'workbook': Missing child element(s)...

result.valid          # bool
result.errors         # list[str] — lxml error messages
result.schema_available  # False if the vendor submodule is not checked out

The same check is available as an MCP tool:

validate_workbook()                       # validate current open workbook in memory
validate_workbook(file_path="out.twb")    # validate a file on disk (.twb or .twbx)

XSD errors are informational — Tableau itself generates workbooks that occasionally deviate from the schema — but recurring errors signal structural problems worth fixing.

Dashboard Layouts

Custom layouts can be built programmatically using a nested layout dictionary or via generate_layout_json for MCP workflows.

Use the canonical layout tree shape for nested dashboards:

{
  "type": "container",
  "direction": "horizontal",
  "children": [
    {"type": "worksheet", "name": "Sidebar", "fixed_size": 160},
    {
      "type": "container",
      "direction": "vertical",
      "children": [
        {"type": "worksheet", "name": "Header", "fixed_size": 80},
        {"type": "worksheet", "name": "Main Chart", "weight": 1}
      ]
    }
  ]
}

For compatibility with older MCP prompts and generated JSON files, add_dashboardalso accepts legacy container aliases and normalizes them recursively:{"type": "horizontal", "children": [...]} and{"type": "vertical", "children": [...]}. Unknown layout node types now raise aclear error instead of silently creating an empty dashboard zone.

Hyper-backed Example

The examples/hyper_and_new_charts.py example uses the Sample - EU Superstore.hyperextract bundled directly in the package (src/cwtwb/references/) and resolves thephysical Orders_* table via Tableau Hyper API before switching the workbook connection.No repository clone is needed — install with pip install "cwtwb[examples]" and run directly.

Workbook Migration

cwtwb includes a migration subsystem for switching an existing .twb to a newdatasource — for example, repointing a workbook built on one Excel file to adifferent Excel with a different schema, or migrating between language variantsof the same dataset.

How it works

Migration is a multi-step workflow. Each step is available as both an MCP tooland a Python function:

1. inspect_target_schema   →  Scan the target Excel and list its columns
2. profile_twb_for_migration  →  Inventory which fields the workbook uses
3. propose_field_mapping   →  Match source fields to target columns (fuzzy)
4. preview_twb_migration   →  Dry-run: show what would change, blockers/warnings
5. apply_twb_migration     →  Write the migrated .twb + JSON reports

migrate_twb_guided is a convenience wrapper that runs steps 2–5 in sequenceand pauses automatically when only low-confidence field matches remain, returninga warning_review_bundle for human review before proceeding.

Python example

from cwtwb.migration import migrate_twb_guided_json
import json

# One-call guided migration
result = migrate_twb_guided_json(
    file_path="templates/SalesDashboard.twb",
    target_source="data/new_data_source.xlsx",
    output_path="output/SalesDashboard_migrated.twb",
)
bundle = json.loads(result)

if bundle["status"] == "warning_review_required":
    # Inspect low-confidence matches and confirm or override them
    print(bundle["warning_review_bundle"])
    # Re-run with confirmed mappings
    result = migrate_twb_guided_json(
        file_path="templates/SalesDashboard.twb",
        target_source="data/new_data_source.xlsx",
        output_path="output/SalesDashboard_migrated.twb",
        mapping_overrides={"Old Field Name": "New Column Name"},
    )

MCP tool example

When using cwtwb as an MCP server, an AI agent can run the full workflow:

inspect_target_schema(target_source="data/new_data_source.xlsx")
→ returns column list and data types

migrate_twb_guided(
    file_path="templates/SalesDashboard.twb",
    target_source="data/new_data_source.xlsx",
    output_path="output/SalesDashboard_migrated.twb"
)
→ returns status: "applied" or "warning_review_required"

Output files

A completed migration writes three files:

Scope parameter

scope="workbook" migrates all worksheets. Pass a worksheet name to limitmigration to a single sheet.

Self-contained example

examples/migrate_workflow/ contains a template .twb, the originalSuperstore Excel, a target Chinese-locale Superstore Excel, and a runnablescript:

python examples/migrate_workflow/test_migration_workflow.py

Project Structure

cwtwb/
|-- src/cwtwb/
|   |-- __init__.py
|   |-- capability_registry.py
|   |-- config.py
|   |-- contracts/
|   |-- authoring_contract.py
|   |-- authoring_run.py
|   |-- charts/
|   |-- connections.py
|   |-- dashboard_actions.py
|   |-- dashboard_dependencies.py
|   |-- dashboard_layouts.py
|   |-- dashboards.py
|   |-- field_registry.py
|   |-- layout.py
|   |-- layout_model.py
|   |-- layout_rendering.py
|   |-- mcp/
|   |-- parameters.py
|   |-- skills/
|   |-- twb_analyzer.py
|   |-- twb_editor.py
|   |-- validator.py
|   `-- server.py
|-- tests/
|-- examples/
|-- docs/
|-- pyproject.toml
`-- README.md

Development

# Install in editable mode
pip install -e .

# Run test suite
pytest --basetemp=output/pytest_tmp

# Run the mixed showcase example
python examples/scripts/demo_all_supported_charts.py

# Run the advanced Hyper-backed example
python examples/scripts/demo_hyper_and_new_charts.py

# Run the guided migration example
python examples/migrate_workflow/test_migration_workflow.py

# Start MCP server
cwtwb

License

AGPL-3.0-or-later