Tableau Public 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