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.
The cw in cwtwb comes from Cooper Wenhua.
Latest update (0.18.9): release refresh for a republish after the previous 0.18.8 artifacts already existed on PyPI.
Author: Cooper Wenhua <imgwho@gmail.com>
Try the example workflow · Read the guide
pip install cwtwbIf you want the bundled Hyper-backed example too:
pip install "cwtwb[examples]"If you want cloud validation (upload to Tableau Cloud):
pip install "cwtwb[validate]"uvx cwtwbAdd 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.
For client-specific details and the full reference, see https://github.com/imgwho/cwtwb/blob/master/docs/guide.md.
| Area | What you get |
|---|---|
| Workbook authoring | Generate .twb / .twbx files from templates or from scratch |
| Chart building | Build bar, line, pie, map, KPI, and dual-axis workbooks |
| Safety | Validate structure and Tableau XSD before publishing |
| Cloud validation | Upload to Tableau Cloud to verify .twb is structurally valid, 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 |
This GIF shows the MCP tool flow that builds a dashboard step by step.
Interfaces
┌───────────────────────────────────────────────────────────────┐
│ ┌──────────────────────────┐ ┌───────────────────────────┐ │
│ │ MCP Server │ │ Python Library │ │
│ │ tools_workbook │ │ from cwtwb.twb_editor │ │
│ │ tools_validate │ │ import TWBEditor │ │
│ │ │ │ │ │
│ │ │ │ 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
▼
┌───────────────────────────────────────────────────────────────┐
│ Cloud Validation (optional) │
│ upload_workbook → Tableau Cloud → screenshot_workbook │
│ Confirms .twb is structurally valid and captures preview │
└───────────────────────────────────────────────────────────────┘
.twb is the workbook XML. .twbx is the packaged version that bundles the workbook together with extracts and images.
No. validate_workbook() checks the workbook in memory or on disk, but it does not write output. save_workbook() is the tool that writes files.
upload_workbook uploads a .twb to Tableau Cloud to verify it is structurally valid. Upload success means Tableau Cloud can parse the workbook. Requires pip install "cwtwb[validate]" and a .env file with Tableau credentials (see .env.example).
- Install:
pip install "cwtwb[validate]" - Copy
.env.exampleto.env - Fill in your Tableau Cloud PAT credentials
- After
save_workbook, callupload_workbookto validate
Use uvx cwtwb for the normal MCP workflow. Use python -m cwtwb.mcp for local testing without uvx.
See the online guide.
AGPL-3.0-or-later