Tableau Local MCP Server

A Model Context Protocol (MCP) server that enables AI assistants like Claude to programmatically read, modify, and query Tableau workbook files (.twb and .twbx) on your local filesystem.

---

What It Does

This MCP server gives AI assistants direct access to Tableau workbook internals. Instead of manually editing XML or clicking through Tableau Desktop menus, you can ask Claude to:

• Inspect workbook structure, fields, calculated fields, parameters, sets, worksheets, and dashboards.
• Create worksheets, dashboards, calculated fields, parameters, sets, groups, bins, aliases, and folders.
• Modify connections, parameter values, field formatting, worksheet encodings, dashboard layouts, and filters.
• Query embedded Hyper extract data using SQL.
• Save with automatic backup creation.

All 80 tools work on both .twb (plain XML) and .twbx (packaged ZIP) formats.

---

Tools Overview

This MCP Server provides an extensive set of 80 tools categorized by their function:

Category	Description
Structure & Metadata	Read workbook structure, list fields, describe worksheets and dashboards.
Calculated Fields	Add, list, and remove calculated fields with Tableau formulas.
Parameters	Add, modify, list, and remove workbook parameters (range/list/all).
Sets, Groups & Bins	Create manual/Top N sets, custom dimension groups, and numeric bin fields.
Formatting & Organization	Set number/date formats, add aliases, organize folders, hide fields.
Worksheets & Dashboards	Create, rename, duplicate, modify, and remove sheets/dashboards.
Visual Encodings & Axes	Manage shelves, rows/cols, reference lines, annotations, tooltip texts, axes ranges.
Filters & Actions	Add/remove datasource, worksheet, or dashboard filters and interactive actions.
Hyper Data Query	Run SQL against extracts, list tables, and describe schema data types.

<details> <summary><strong>Full Tool List (80 tools)</strong></summary>

Metadata & Inspection Tools

• tableau_read_workbook_structure: Parse and display the full structure of a Tableau Workbook (.twb or .twbx) file.
• tableau_list_fields: List all fields (columns) in a specific datasource of a Tableau workbook.
• tableau_list_worksheets: List all worksheets in a workbook with basic info (name, mark type, datasource).
• tableau_list_dashboards: List all dashboards in a workbook with size and zone info.
• tableau_analyze_visuals: Analyze the visual configuration of worksheets and dashboards in a Tableau workbook.
• tableau_get_field_dependencies: Analyze where a specific field is used across the entire workbook.
• tableau_list_tooltips: Extract and display tooltip configurations for all worksheets.

Calculated Fields & Parameters

• tableau_list_calculated_fields: List all calculated fields and their formulas in a datasource.
• tableau_add_calculated_field: Add a new calculated field to a datasource in a Tableau workbook.
• tableau_remove_calculated_field: Remove a calculated field from a datasource.
• tableau_list_parameters: List all parameters defined in a Tableau workbook with their values and types.
• tableau_add_parameter: Add a new parameter to a Tableau workbook.
• tableau_modify_parameter: Modify an existing parameter's value, range, or allowed values.
• tableau_remove_parameter: Remove a parameter from a Tableau workbook.
• tableau_add_table_calculation: Add a table calculation to a worksheet.

Sets, Groups, and Bins

• tableau_list_sets: List all sets defined in a datasource.
• tableau_add_set: Add a set to a datasource in a Tableau workbook.
• tableau_remove_set: Remove a set from a datasource.
• tableau_add_group: Add a custom group to a datasource (combines dimension values into named groups).
• tableau_add_bin: Add a bin field to a datasource (groups numeric values into ranges).

Organization & Formatting

• tableau_format_field: Set the number or date format on a field in a datasource.
• tableau_add_alias: Add aliases (renamed display values) to a dimension field.
• tableau_organize_folders: Create or update a folder in a datasource to organize fields.
• tableau_hide_field: Hide or unhide a field in the data pane.
• tableau_set_field_description: Set or update the description/comment on a field.
• tableau_set_default_aggregation: Set the default aggregation for a measure field.
• tableau_convert_field_role: Convert a field between dimension and measure roles.
• tableau_set_geo_role: Assign geographic roles to fields.

Filters & Actions

• tableau_list_filters: List all filters across worksheets and datasources in a workbook.
• tableau_add_datasource_filter: Add a pre-filter at the datasource level.
• tableau_remove_datasource_filter: Remove a datasource-level filter.
• tableau_add_worksheet_filter: Add a categorical or quantitative filter to a worksheet.
• tableau_add_relative_date_filter: Add a relative date filter to a worksheet.
• tableau_remove_worksheet_filter: Remove a filter from a worksheet.
• tableau_add_dashboard_filter: Add a quick filter card to a dashboard.
• tableau_list_actions: List all actions in a Tableau workbook with full details.
• tableau_add_action: Add a filter, highlight, or URL action to a dashboard.
• tableau_remove_action: Remove an action from the workbook by name.

Worksheets & Encodings

• tableau_create_worksheet: Create a new worksheet in a Tableau workbook.
• tableau_duplicate_worksheet: Clone an existing worksheet to create a copy.
• tableau_rename_worksheet: Rename a worksheet and update all references throughout the workbook.
• tableau_remove_worksheet: Remove a worksheet and clean up all references.
• tableau_modify_worksheet: Edit worksheet marks and visual configurations.
• tableau_add_encoding: Assign fields to visual shelves (Color, Size, Label, Detail, Tooltip).
• tableau_remove_encoding: Remove a field from a worksheet encoding shelf.
• tableau_set_mark_type: Change the mark type of a worksheet (Bar, Line, Area, etc).
• tableau_swap_rows_cols: Swap the Rows and Columns shelves on a worksheet.
• tableau_reorder_shelves: Reorder fields on specific shelves.
• tableau_add_sort: Add sorting to a worksheet field.
• tableau_remove_sort: Remove a sort from a worksheet.
• tableau_add_totals: Add Grand Totals to a worksheet.
• tableau_set_color_palette: Apply a custom color palette.
• tableau_create_combo_chart: Create a dual-axis combo chart.

Design, Axes & Annotations

• tableau_set_axis: Configure axis properties: title, range, gridlines, etc.
• tableau_add_reference_line: Add reference lines to continuous axes.
• tableau_remove_reference_line: Remove a reference line from a worksheet.
• tableau_add_annotation: Add a text annotation to a worksheet.
• tableau_remove_annotation: Remove annotations from a worksheet.
• tableau_set_tooltip: Set or replace customized tooltip text on a worksheet.
• tableau_set_worksheet_title: Set or hide a worksheet title with custom formatted text.
• tableau_set_worksheet_format: Format worksheet fonts, shading, lines.
• tableau_apply_theme: Apply a comprehensive visual theme across worksheets.
• tableau_set_worksheet_size: Set the worksheet size/fit mode.
• tableau_set_legend: Show or hide a legend.

Dashboards & Layouts

• tableau_create_dashboard: Create a new dashboard.
• tableau_rename_dashboard: Rename a dashboard and update references.
• tableau_remove_dashboard: Remove a dashboard from the workbook.
• tableau_modify_dashboard: Edit dashboard layout configuration.
• tableau_add_dashboard_object: Add objects (text, image, web page) to a dashboard.
• tableau_add_dashboard_container: Add horizontal/vertical layout containers.
• tableau_build_layout_tree: Rebuild a dashboard's layout using a hierarchical tree.
• tableau_set_dashboard_layout: Reposition or resize a zone in a dashboard.
• tableau_set_dashboard_size: Set the dashboard size constraints.

Connection & Save Tools

• tableau_modify_connection: Modify the connection details of a datasource.
• tableau_set_datasource_caption: Set or update the display name of a datasource.
• tableau_list_custom_sql: Extract and display all Custom SQL queries.
• tableau_save_workbook: Save a modified workbook back to disk.

Hyper Data Query Tools

• tableau_list_hyper_tables: List all tables and schemas in a .hyper extract file.
• tableau_describe_hyper_table: Show column names, data types, and nullability for a table.
• tableau_query_hyper: Run a SQL query against a Tableau Hyper extract file.

</details>

---

Prerequisites

• Python 3.10+
• Tableau Hyper API — requires a compatible OS (macOS, Windows, or Linux x86_64)
• Claude Desktop (or any MCP-compatible client)

---

Installation

1. Clone the repository

git clone https://github.com/Evgenzh2007/tableau-local-mcp.git
cd tableau-local-mcp

2. Create a virtual environment (recommended)

python3 -m venv venv
source venv/bin/activate  # macOS/Linux
# or: venv\Scripts\activate  # Windows

3. Install dependencies

pip install -r requirements.txt

4. Verify installation

python server.py
# Should start the MCP server via stdio (will wait for input from an MCP client)

---

Configuration

Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tableau_local": {
      "command": "python",
      "args": ["/absolute/path/to/tableau-local-mcp/server.py"],
      "env": {}
    }
  }
}

Tip: If using a virtual environment, point command to the venv's Python:

"command": "/absolute/path/to/tableau-local-mcp/venv/bin/python"

After saving, restart Claude Desktop to pick up the new server.

---

Usage Examples

Once configured, you can interact with Tableau workbooks through natural language in Claude:

Explore a workbook

"Read the structure of my Superstore workbook at ~/Documents/My Tableau Repository/Workbooks/Superstore.twbx"

Add a calculated field

"Add a Profit Margin calculated field using the formula [Profit] / [Sales] to the Superstore workbook"

Create a visualization

"Create a new worksheet called 'Sales Trend'. Add Order Date (Month) to Columns and Sales to Rows. Change mark type to Line."

Build a dashboard

"Create a dashboard named 'Overview'. Add the 'Sales Trend' and 'Regional Profit' worksheets side-by-side using horizontal container."

Query extract data

"How many orders are there per category? Query the Hyper extract in Superstore.twbx"

Batch modifications

"Add a Region Groups group that maps states to Northeast, Southeast, West Coast, and Midwest — then add a Sales bin at $500 intervals — then format Profit as currency — then save"

---

How It Works

Claude Desktop ←→ MCP Protocol (stdio) ←→ server.py
                                              │
                                    ┌─────────┼─────────┐
                                    │         │         │
                                  lxml    Hyper API   Python
                                    │         │       stdlib
                              .twb/.twbx   .hyper    zipfile
                              XML editing  SQL query  archive

• XML Modification: Uses lxml to parse and modify Tableau's XML structure inside .twb files. Handles the specific XML schema requirements for each element type.
• TWBX Support: Automatically extracts .twb from .twbx ZIP archives for editing, and properly re-zips when saving.
• Hyper Queries: Uses the official Tableau Hyper API to run SQL queries against embedded .hyper extract files.
• Backup Safety: Creates timestamped .bak files before overwriting any workbook.

---

Important Notes

• Save workflow: All modification tools operate in memory. Call tableau_save_workbook to persist changes to disk.
• Datasource auto-selection: If a workbook has only one datasource, it's automatically selected. Otherwise, the tool prompts you to specify which one.
• Absolute paths required: All tools expect absolute file paths to workbook files.
• Backup by default: tableau_save_workbook creates a .bak backup before overwriting. Disable with create_backup: false.

---

Project Structure

tableau-local-mcp/
├── server.py           # MCP server with all 80 tools
├── requirements.txt    # Python dependencies
├── README.md           # This file
├── LICENSE             # MIT License
└── .gitignore          # Python/OS gitignore

---

Tech Stack

• Python 3.10+ — server runtime
• MCP SDK (mcp) — Model Context Protocol framework
• lxml — fast XML parsing and manipulation
• Tableau Hyper API — SQL queries on .hyper extract files
• Pydantic — input validation and schema definitions

---

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Commit your changes (git commit -m 'Add my feature')
4. Push to the branch (git push origin feature/my-feature)
5. Open a Pull Request

---

License

This project is licensed under the MIT License — see the LICENSE file for details.

---

Acknowledgments

• Anthropic for Claude and the MCP protocol
• Tableau for the Hyper API
• Built with assistance from Claude