Tableau Public MCP Server

A Model Context Protocol (MCP) server that enables AI applications to interact with Tableau Public content programmatically. This server provides 22 tools for accessing user profiles, workbooks, visualisations, social connections, discovery features, and workbook analysis through Tableau Public's REST APIs.

Features

• 22 Comprehensive Tools covering all major Tableau Public API endpoints and workbook analysis
• No Authentication Required - all endpoints are public
• Type-Safe - built with TypeScript and Zod schema validation
• Well-Tested - comprehensive test coverage with Vitest
• MCP Standard - follows Model Context Protocol specifications
• Easy Integration - works with Claude Desktop and other MCP clients
• TWBX Analysis - extract calculations, data profiles, and structure from downloaded workbooks

Table of Contents

• Installation
• Quick Start
• Available Tools
• Usage Examples
• Configuration
• Development
• Testing
• Architecture
• Contributing
• License

Installation

Prerequisites

• Node.js 20 or higher (includes npm and npx)

Install via npm (Recommended)

No local setup needed — run directly with npx:

{
  "mcpServers": {
    "tableau-public": {
      "command": "npx",
      "args": ["-y", "@wjsutton/tableau-public-mcp-server@latest"]
    }
  }
}

Add this to your MCP client configuration file (see Quick Start for file locations).

Install from Source

Alternatively, clone and build locally:

# Clone the repository
git clone https://github.com/wjsutton/tableau-public-mcp.git
cd tableau-public-mcp

# Install dependencies
npm install

# Build the project
npm run build

Quick Start

Video Setup Guide for Claude Desktop and VSCode (GitHub Copilot)

Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

Location:

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

Configuration (npm):

{
  "mcpServers": {
    "tableau-public": {
      "command": "npx",
      "args": ["-y", "@wjsutton/tableau-public-mcp-server@latest"]
    }
  }
}

Configuration (from source):

{
  "mcpServers": {
    "tableau-public": {
      "command": "node",
      "args": ["/absolute/path/to/tableau-public-mcp/build/index.js"]
    }
  }
}

Available Tools

The server provides 22 tools organised into 6 categories:

User Profile Tools (3)

| Tool | Description | API Reference | |------|-------------|---------------| | get_user_profile | Returns comprehensive profile data including display name, location, bio, workbook counts, follower/following counts, favourites count, social media links, website URL, freelance status, and the user's last 21 workbooks with metadata | Profile API | | get_user_profile_categories | Returns user-defined workbook categories with contained workbooks, view counts, favourites, and engagement metrics. Supports pagination (max 500 categories). Returns empty array if user hasn't configured categories | Profile Categories API | | get_user_profile_basic | Returns essential profile metadata in a lightweight format including profileName, displayName, and basic user information. Faster alternative when you only need core profile details without workbook history | Profile API |

Workbook Tools (4)

| Tool | Description | API Reference | |------|-------------|---------------| | get_workbooks_list | Returns paginated array of workbooks including titles, URLs, view counts, publication dates, thumbnails, and sheet/dashboard counts. Supports pagination (max 50 per request) and visibility filtering (NON_HIDDEN or ALL) | Workbooks API | | get_workbook_details | Returns detailed metadata for a single workbook including title, author, view count, favourite count, publication date, default view URL, allowDataAccess flag, and complete view listing | Workbook Details API | | get_workbook_contents | Returns complete workbook structure with all sheets, dashboards, data sources, and detailed view information including descriptions, sheet types, and repository URLs | Workbook Contents API | | get_related_workbooks | Returns up to 20 recommended workbooks based on content similarity, including titles, authors, view counts, and thumbnails | Related Workbooks API |

Social Tools (3)

| Tool | Description | API Reference | |------|-------------|---------------| | get_followers | Returns paginated array of followers with usernames, display names, bios, and their latest workbook details. Supports pagination (max 24 per request, index increments by count: 0, 24, 48...) | Followers API | | get_following | Returns paginated array of accounts the user follows with usernames, display names, bios, and their latest workbook details. Supports pagination (max 24 per request) | Following API | | get_favorites | Returns array of workbook repository URLs that the user has favourited/bookmarked. Includes workbook metadata and URLs for accessing the visualisations | Favourites API |

Discovery Tools (3)

| Tool | Description | API Reference | |------|-------------|---------------| | search_visualizations | Returns ranked search results for visualisations or authors matching the query. Supports type filtering (vizzes/authors), pagination (max 20 per request), and returns titles, authors, view counts, thumbnails, and URLs | Search API | | get_viz_of_day | Returns paginated list of Tableau Public's featured Viz of the Day winners with titles, authors, descriptions, publication dates, view counts, and workbook URLs. Supports pagination (max 12 per page) | VOTD API | | get_featured_authors | Returns list of featured authors (Hall of Fame Visionaries, Tableau Visionaries, or Ambassadors) with profile information, workbook counts, follower counts, and featured workbooks | Featured Authors API |

Media Tools (2)

| Tool | Description | API Reference | |------|-------------|---------------| | get_workbook_image | Returns URL to full-size PNG screenshot of a visualisation. Requires workbookUrl (e.g., "username/workbook-name") and viewName (sheet/dashboard name). Image displays static visualisation without interactivity | Workbook Image API | | get_workbook_thumbnail | Returns URL to thumbnail-sized preview image of a visualisation. Requires workbookUrl and viewName. Smaller file size ideal for gallery views and previews | Workbook Thumbnail API |

TWBX Analysis Tools (7)

| Tool | Description | API Reference | |------|-------------|---------------| | download_workbook_twbx | Downloads .twbx file to local temp directory. First verifies allowDataAccess flag, then downloads the workbook containing XML definition, data extracts, and embedded assets. Returns file path, size, and metadata | Download Workbook API | | unpack_twbx | Extracts contents from .twbx ZIP archive. Returns paths to main TWB file, data sources, and embedded files. Creates organised directory structure with workbook XML, data extracts, images, and other assets | Local processing | | get_twbx_calculated_fields | Parses TWB XML to extract calculated fields, parameters, and source fields. Returns formulas, data types, field roles, dependencies, and supports hidden field filtering. Includes dependency analysis showing root and leaf calculations | Local processing | | get_twbx_workbook_structure | Analyses workbook XML to return complete structure including worksheets, dashboards, data sources, connections, and sheet hierarchy. Shows workbook organisation and data source relationships | Local processing | | get_twbx_calculation_dependencies | Builds dependency graph of calculated fields showing which calculations depend on others. Returns dependency chains, orphaned calculations, and complexity metrics to understand calculation architecture | Local processing | | get_twbx_lod_expressions | Identifies and extracts Level of Detail (LOD) expressions (FIXED, INCLUDE, EXCLUDE) from calculated fields. Returns LOD type, formula, scope, aggregation, and affected dimensions for each expression | Local processing | | get_twbx_data_profile | Profiles embedded data files (CSV, Excel, JSON, images) extracting statistics, column info, data types, sample values, and data quality metrics. Returns row counts, column summaries, and data distributions | Local processing |

Usage Examples

Visit https://wjsutton.github.io/tableau-public-mcp-examples/ for:

• Use Cases
• Examples
• Prompt Templates

Configuration

Environment Variables

No environment variables are needed by default. The server supports the following optional environment variables:

| Variable | Description | Default | |----------|-------------|---------| | MAX_RESULT_LIMIT | Maximum results for paginated queries | 1000 | | LOG_LEVEL | Logging verbosity (debug, info, warn, error) | info | | API_TIMEOUT | Request timeout in milliseconds | 30000 | | TABLEAU_PUBLIC_BASE_URL | Base URL for Tableau Public API | https://public.tableau.com |

Development

Project Structure

tableau-public-mcp/
├── src/
│   ├── index.ts              # Entry point
│   ├── server.ts             # MCP server setup
│   ├── config.ts             # Configuration
│   ├── tools/
│   │   ├── tool.ts           # Base Tool class
│   │   ├── toolName.ts       # Tool name types
│   │   ├── tools.ts          # Tool registry
│   │   ├── getUserProfile/   # Tool implementation
│   │   │   ├── getUserProfile.ts
│   │   │   └── getUserProfile.test.ts
│   │   └── ...               # Other tools (16 total)
│   └── utils/
│       ├── apiClient.ts      # HTTP client
│       ├── pagination.ts     # Pagination helpers
│       └── errorHandling.ts  # Error utilities
├── build/                    # Compiled output
├── package.json
├── tsconfig.json
└── vitest.config.ts

Development Commands

# Install dependencies
npm install

# Build TypeScript
npm run build

# Watch mode (rebuild on changes)
npm run dev

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

Testing

The project uses Vitest for testing with comprehensive coverage:

# Run all tests
npm test

# Run with coverage report
npm run test:coverage

# Run in watch mode for development
npm run test:watch

Test Structure

Each tool has its own test file that covers:

• Metadata validation (name, description)
• Successful API calls with mocked responses
• Error handling (404, network errors, etc.)
• Parameter validation with Zod schemas
• Pagination support where applicable

Architecture

System Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        MCP Client                                │
│                  (Claude Desktop, etc.)                          │
└───────────────────────────┬─────────────────────────────────────┘
                            │ stdio
                            │ MCP Protocol
┌───────────────────────────▼─────────────────────────────────────┐
│                    Tableau Public MCP Server                     │
│                                                                   │
│  ┌─────────────────────────────────────────────────────────┐   │
│  │              Server (server.ts)                          │   │
│  │         - MCP Protocol Handler                           │   │
│  │         - Tool Registration                              │   │
│  │         - Request/Response Management                    │   │
│  └─────────────────────┬───────────────────────────────────┘   │
│                        │                                         │
│  ┌─────────────────────▼───────────────────────────────────┐   │
│  │           Tool Registry (tools.ts)                       │   │
│  │         22 Tool Factories                                │   │
│  └─────────┬──────────┬──────────┬──────────┬──────────────┘   │
│            │          │          │          │                   │
│  ┌─────────▼──┐  ┌───▼────┐  ┌─▼─────┐  ┌─▼────────┐  ...    │
│  │ User       │  │Workbook│  │Social │  │Discovery │          │
│  │ Profile    │  │ Tools  │  │Tools  │  │  Tools   │          │
│  │ Tools (3)  │  │  (4)   │  │  (3)  │  │   (3)    │          │
│  └─────┬──────┘  └───┬────┘  └─┬─────┘  └─┬────────┘          │
│        │             │          │          │                    │
│  ┌─────▼─────────────▼──────────▼──────────▼────────────────┐  │
│  │              Utilities Layer                              │  │
│  │  ┌──────────┐  ┌──────────┐  ┌─────────┐  ┌──────────┐  │  │
│  │  │ Cached   │  │  Error   │  │   URL   │  │  Config  │  │  │
│  │  │ API      │  │ Handling │  │ Builder │  │          │  │  │
│  │  │ Client   │  │          │  │         │  │          │  │  │
│  │  └─────┬────┘  └──────────┘  └─────────┘  └──────────┘  │  │
│  └────────┼───────────────────────────────────────────────────┘  │
└───────────┼──────────────────────────────────────────────────────┘
            │ HTTPS
            │
┌───────────▼──────────────────────────────────────────────────────┐
│              Tableau Public REST APIs                             │
│                                                                    │
│  /profile/api/*        - User profiles and workbooks              │
│  /public/apis/bff/*    - Search and discovery                     │
│  /views/*              - Workbook images and thumbnails           │
└────────────────────────────────────────────────────────────────────┘

Design Patterns

• Factory Pattern: Each tool is created by a factory function
• Type Safety: Full TypeScript typing with Zod schema validation
• Error Handling: Consistent error responses with helpful messages
• Modularity: Tools are independent and self-contained
• Testability: Mocked API clients for unit testing

Technology Stack

| Component | Technology | Purpose | |-----------|-----------|---------| | Runtime | Node.js 20+ | JavaScript runtime | | Language | TypeScript 5.7+ | Type safety and modern JS | | MCP SDK | @modelcontextprotocol/sdk | MCP protocol implementation | | Validation | Zod | Schema validation | | Testing | Vitest | Unit and integration tests | | HTTP Client | Axios | API requests |

Key Features

• No Authentication: All Tableau Public APIs are public
• Stdio Transport Only: Designed for local MCP client integration
• Comprehensive Error Handling: Detailed error messages with suggestions
• Pagination Support: Built-in helpers for multi-page results
• Logging: Request/response logging to stderr (stdout reserved for MCP)

API Reference

All tools interact with Tableau Public REST APIs. Key endpoints:

| Endpoint Category | Base Path | Documentation | |------------------|-----------|---------------| | User Profiles | /profile/api/{username} | User metadata and workbooks | | Workbooks | /public/apis/workbooks | Workbook listings and details | | Social | /profile/api/followers/ | Followers, following, favourites | | Search | /api/search/query | Content discovery | | Discovery | /public/apis/bff/discover/ | Featured content | | Images | /views/ and /thumb/views/ | Visualisation media |

Troubleshooting

Common Issues

Issue: Server fails to start

• Solution: Ensure Node.js 20+ is installed and dependencies are up to date

Issue: Tools return 404 errors

• Solution: Verify usernames and workbook URLs are correct and publicly accessible

Issue: Rate limiting errors

• Solution: Reduce request frequency or implement delays between calls

Issue: TypeScript compilation errors

• Solution: Run npm install to ensure all types are installed

Logging

The server logs to stderr (stdout is reserved for MCP protocol). Set LOG_LEVEL=debug for detailed logging:

LOG_LEVEL=debug node ./build/index.js 2> server.log

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run tests and linting (npm test && npm run lint)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow the existing code style and patterns
• Write comprehensive tests for new features
• Update documentation for API changes
• Use meaningful commit messages
• Ensure all tests pass before submitting PR

Related Resources

• Model Context Protocol Documentation
• Tableau Public API Reference
• Reference Implementation: tableau-mcp
• Claude Desktop
• MCP Inspector

License

MIT License - see LICENSE file for details

Acknowledgments

• Built following the architecture patterns from tableau/tableau-mcp
• Tableau Public API documentation by @wjsutton
• Model Context Protocol by Anthropic

Support

Enjoy this project? Support it in Tableau's Hackathon

For issues and questions:

• Open an issue on GitHub Issues
• Check existing issues for solutions
• Provide detailed reproduction steps for bugs

Made with ❤️ for the Tableau Public and MCP communities