Cwtwb

by imgwho

165 downloads

Not rated

GitHub

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…

Details

Author: imgwho
Downloads: 165
Categories: Productivity, Other, AI

- MCP tools for guided authoring runs and workbook creation
- Python library with TWBEditor for scripted workbook engineering
- Supports .twb and .twbx files transparently
- Worksheet clone and refactor with identity normalization
- Built-in chart primitives (bar, pie, map, text, etc.) and dashboard composition
- XML-based engine using lxml for patching and validation

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 Cwtwb

Command (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

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

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

JSON

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

JSON

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

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

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

JSON

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

JSON

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

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

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

JSON

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

JSON

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

From the repository

Install via pip install cwtwb. As an MCP server, configure your client to launch with uvx cwtwb. As a Python library, use TWBEditor to open templates, add fields, build worksheets, assemble dashboards, and save .twb or .twbx files. Cwtwb also supports a guided datasource-first authoring run with confirmation gates.

`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}

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"
        ]
    }
}

cwtwb

> Tableau Workbook (.twb/.twbx) generation toolkit for reproducible dashboards and workbook engineering > Programmatically create Tableau workbooks with stable analytical primitives, dashboard composition, and built-in structural validation. Author: Cooper Wenhua <imgwho@gmail.com>

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, addcwtwbto 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.jsonon 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 tocommand4. Set Name tocwtwb5. Set Command touvx cwtwbClaude Code`bash claude mcp add cwtwb -- uvx cwtwb`VSCode Open the workspace.vscode/mcp.json file or your user-profile mcp.jsonfile 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 sameuvx cwtwbcommand through the guided flow. For local testing withoutuvx, you can also start the server with:`bash python -m cwtwb.mcp`As Python Library UseTWBEditor(...)to start from a template and rebuild workbook content. UseTWBEditor.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 TableauCalculation_

 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 TWBEditor

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

create_workbook

open_workbook

list_fields

list_worksheets

list_dashboards

add_calculated_field

remove_calculated_field

add_parameter

add_worksheet

clone_worksheet

preview_worksheet_refactor

apply_worksheet_refactor

set_worksheet_caption

set_worksheet_hidden

configure_chart

configure_dual_axis

configure_worksheet_style

configure_chart_recipe

set_mysql_connection

set_tableauserver_connection

set_excel_connection

set_csv_connection

set_hyper_connection

add_dashboard

add_dashboard_action

save_workbook

generate_layout_json

inspect_target_schema

profile_twb_for_migration

propose_field_mapping

preview_twb_migration

apply_twb_migration

list_capabilities

describe_capability

analyze_twb

diff_template_gap

validate_workbook

inspect_excel_connection

upload_workbook

screenshot_workbook

Claude Desktop / Cursor

McpServers

cwtwb

Overview

Installation

Requirements

Quick Start

As MCP Server

Claude Desktop

Cursor IDE

Claude Code

VSCode

As Python Library

Clone and Refactor an Existing Worksheet

Working with Packaged Workbooks (.twbx)

Install

More like this

Sequential Thinking

Time

Filesystem

EverArt

Google Drive

Context 7

`create_workbook`

`open_workbook`

`list_fields`

`list_worksheets`

`list_dashboards`

`add_calculated_field`

`remove_calculated_field`

`add_parameter`

`add_worksheet`

`clone_worksheet`

`preview_worksheet_refactor`

`apply_worksheet_refactor`

`set_worksheet_caption`

`set_worksheet_hidden`

`configure_chart`

`configure_dual_axis`

`configure_worksheet_style`

`configure_chart_recipe`

`set_mysql_connection`

`set_tableauserver_connection`

`set_excel_connection`

`set_csv_connection`

`set_hyper_connection`

`add_dashboard`

`add_dashboard_action`

`save_workbook`

`generate_layout_json`

`inspect_target_schema`

`profile_twb_for_migration`

`propose_field_mapping`

`preview_twb_migration`

`apply_twb_migration`

`list_capabilities`

`describe_capability`

`analyze_twb`

`diff_template_gap`

`validate_workbook`

`inspect_excel_connection`

`upload_workbook`

`screenshot_workbook`