Cwtwb
About
Cwtwb is a Model Context Protocol (MCP) server and Python toolkit for programmatically generating Tableau Desktop workbook files (.twb / .twbx) from code or AI-driven tool calls. It is designed as a workbook engineering layer to make workbook generation reproducible…
Explore
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.
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
CwtwbCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
``bash`
pip install cwtwb
To run the bundled Hyper-backed example that inspects files andOrders_*
resolves the physical table automatically, install the optional`
example dependency as well:
bash``
pip install "cwtwb[examples]"
pip install -e .
create_workbook
Create a new workbook from a TWB or TWBX template file.
open_workbook
Open an existing workbook (.twb or .twbx) for in-place worksheet editing.
list_fields
List all available fields in the current workbook datasource.
list_worksheets
List worksheet names in the current workbook.
list_dashboards
List dashboards and their worksheet zones in the current workbook.
add_calculated_field
Add a calculated field to the datasource.
remove_calculated_field
Remove a previously added calculated field.
add_parameter
Add a parameter to the workbook.
add_worksheet
Add a new blank worksheet to the workbook.
clone_worksheet
Clone an existing worksheet and its worksheet window.
preview_worksheet_refactor
Preview worksheet-scoped field rewrites without mutating the workbook.
apply_worksheet_refactor
Rewrite one worksheet to use replacement fields without touching others.
set_worksheet_caption
Set or clear a plain-text worksheet caption.
set_worksheet_hidden
Hide or unhide a worksheet tab by updating worksheet window metadata.
configure_chart
Configure chart type and field mappings for a worksheet.
configure_dual_axis
Configure a dual-axis chart composition.
configure_worksheet_style
Apply worksheet-level styling: background color, axis/grid/border visibility.
configure_chart_recipe
Configure a showcase recipe chart through the shared recipe registry.
set_mysql_connection
Configure the workbook datasource to use a local MySQL connection.
set_tableauserver_connection
Configure the workbook datasource to use a Tableau Server connection.
set_excel_connection
Configure the workbook datasource to use a local Excel connection.
set_csv_connection
Configure the workbook datasource to use a local CSV connection.
set_hyper_connection
Configure the workbook datasource to use a local Hyper extract connection.
add_dashboard
Create a dashboard combining multiple worksheets.
add_dashboard_action
Add an interaction action to a dashboard.
save_workbook
Save the workbook as a TWB 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.
generate_layout_json
Generate and save a dashboard layout JSON file.
inspect_target_schema
Inspect the first-sheet schema of a target Excel datasource.
profile_twb_for_migration
Profile workbook datasources and worksheet scope before migration.
propose_field_mapping
Scan source and target schema and propose a field mapping.
preview_twb_migration
Preview a workbook migration onto a target datasource.
apply_twb_migration
Apply a workbook migration and write a migrated TWB plus reports.
list_capabilities
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.
describe_capability
Describe one declared capability and its support tier.
analyze_twb
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.
diff_template_gap
Summarize the non-core capability gap of a TWB template.
validate_workbook
Validate a workbook against the official Tableau TWB XSD schema (2026.1). 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.
inspect_excel_connection
Preview how an Excel workbook will be interpreted before connection setup.
upload_workbook
Upload a .twb/.twbx to Tableau Cloud to validate it. Upload success means the workbook structure is valid and Tableau Cloud can parse it. Use this after saving a generated workbook to verify correctness. 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. Returns: {success, workbook_id, workbook_url, views, twbx_path, twbx_size_kb, error}
screenshot_workbook
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). Returns: {success, path, view_name, view_id, size_kb, error}
| Tool | Description |
|---|---|
| start_authoring_run | Create a guided datasource-first authoring run and persist its manifest under tmp/agentic_run/{run_id}/ |
| list_authoring_runs | List previously created authoring runs, their current status, and available artifacts |
| get_run_status | Inspect one authoring run, including confirmation gates, current artifact versions, and failure details |
| resume_authoring_run | Re-open a previous authoring run after a client or server restart |
| intake_datasource_schema | Read the run datasource from the manifest and persist a structured schema summary for Excel or Hyper |
| build_analysis_brief | Create the analysis brief scaffold from the current schema summary |
| finalize_analysis_brief | Finalize 2-4 candidate directions plus the selected direction for the run |
| draft_authoring_contract | Create a contract draft from the schema summary plus a human brief |
| review_authoring_contract_for_run | Review the current draft, apply profile-aware defaults, and produce clarification guidance |
| finalize_authoring_contract | Merge review output with human answers and persist the finalized contract |
| interactive_stage_confirmation | Prefer MCP elicitation for schema, analysis, contract, and wireframe confirmation, with chat fallback when unsupported |
| confirm_authoring_stage | Persist an approval or rejection for schema, analysis, contract, wireframe, or execution_plan after a fresh confirmation request |
| build_wireframe | Build a reviewable wireframe artifact from the confirmed contract |
| finalize_wireframe | Finalize the wireframe review, including layout notes and supported actions |
| reopen_authoring_stage | Reopen analysis, contract, wireframe, or execution_plan after a rejection or downstream scope change |
| build_execution_plan | Convert the finalized contract into a mechanical MCP tool-call plan |
| generate_workbook_from_run | Execute the confirmed plan, save the workbook, and persist validation and analysis reports |
| create_workbook | Load a .twb or .twbx template and initialize a rebuild-from-template workspace |
| open_workbook | Open an existing .twb or .twbx and keep its worksheets and dashboards for editing |
| list_fields | List all available dimensions and measures |
| list_worksheets | List worksheet names in the active workbook |
| list_dashboards | List dashboards and the worksheet zones they reference |
| add_parameter | Add an interactive parameter for what-if analysis |
| add_calculated_field | Add a calculated field with Tableau formula |
| remove_calculated_field | Remove a previously added calculated field |
| clone_worksheet | Clone an existing worksheet and its worksheet window |
| preview_worksheet_refactor | Preview worksheet-scoped field rewrites before mutating the workbook |
| apply_worksheet_refactor | Apply worksheet-scoped field rewrites while preserving the original worksheet |
| add_worksheet | Add a new blank worksheet |
| configure_chart | Configure chart type and field mappings |
| configure_worksheet_style | Apply worksheet-level styling: background color, axis/grid/border visibility |
| configure_dual_axis | Configure a dual-axis chart composition |
| configure_chart_recipe | Configure a showcase recipe chart such as lollipop, donut, butterfly, or calendar |
| add_dashboard | Create a dashboard combining worksheets |
| add_dashboard_action | Add filter, highlight, URL, or go-to-sheet actions to a dashboard |
| set_worksheet_caption | Set or clear a worksheet caption using plain text |
| set_worksheet_hidden | Hide or unhide a worksheet by updating its worksheet window metadata |
| generate_layout_json | Build an interactive structured dashboard flexbox layout |
| list_capabilities | Show cwtwb's declared support boundary |
| describe_capability | Explain whether a chart or feature is core, advanced, recipe, or unsupported |
| analyze_twb | Analyze a .twb file against the capability catalog; output includes both the full capability breakdown and the capability gap triage summary |
| diff_template_gap | Summarize the non-core gap of a template |
| validate_workbook | Validate a workbook against the official Tableau TWB XSD schema (2026.1) |
| migrate_twb_guided | Run the built-in TWB migration workflow and pause for warning confirmation when needed |
| set_excel_connection | Configure the datasource to use a local Excel workbook and register fields from the selected sheet |
| set_mysql_connection | Configure the datasource to use a local MySQL connection |
| set_tableauserver_connection | Configure connection to an online Tableau Server |
| set_hyper_connection | Configure the datasource to use a local Hyper extract connection |
| save_workbook | Save the workbook as .twb (plain XML) or .twbx (ZIP with bundled extracts and images) |
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"
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"cwtwb": {
"cwtwb": {
"command": "uvx",
"args": [
"cwtwb"
]
}
}
}
}McpServers
{
"cwtwb": {
"command": "uvx",
"args": [
"cwtwb"
]
}
}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 workflow
that 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
`bash
pip install cwtwb
`
To run the bundled Hyper-backed example that inspects .hyper files and
resolves the physical Orders_ table automatically, install the optional
example dependency as well:
`bash
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 cwtwb
to that client's MCP configuration.
The launch command is the same across clients:
`bash
uvx cwtwb
`
Each client stores this command in a different configuration format. Use the
matching 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:
`json
{
"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
`bash
claude mcp add cwtwb -- uvx cwtwb
`
VSCode
Open the workspace .vscode/mcp.json file or your user-profile mcp.json
file and add:
`json
{
"servers": {
"cwtwb": {
"command": "uvx",
"args": ["cwtwb"]
}
}
}
`
In VSCode, you can open these files from the Command Palette with
MCP: Open Workspace Folder Configuration or
MCP: Open User Configuration. You can also use MCP: Add Server and
enter the same uvx cwtwb command through the guided flow.
For local testing without uvx, you can also start the server with:
`bash
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 worksheets
and dashboards and reconfigure a sheet in place.
`python
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 visual
module and rebind only the cloned worksheet to a different core measure. This
is especially useful for KPI cards such as turning a Sales KPI worksheet into
an independent Profit KPI worksheet while preserving the original sheet.
`python
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 identity
normalization pass for generic Tableau Calculation_ fields. This stabilizes
pill labels after clone-and-replace workflows and returns post_process
evidence describing renamed calculation identities and worksheet-local rewrite
maps.
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:
``python
from cwtwb.twb_editor import TWBEditorSign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
