tableau-mcp

Implements the Model Context Protocol specification by extending McpServer from @modelcontextprotocol/sdk and dynamically registering tools via a toolFactories pattern. Supports both stdio transport for local process communication and HTTP/StreamableHTTPServerTransport via Express for remote deployment. Tool registration can be filtered at startup using INCLUDE_TOOLS/EXCLUDE_TOOLS environment variables, enabling selective capability exposure without code changes. The Server class handles session management in HTTP mode and wires all subsystems (auth, config, logging) during initialization via startServer().

Exposes query-datasource and list-fields tools that translate natural language or structured queries into Tableau's VizQL Data Service API calls. The implementation wraps RestApi layer calls that handle VizQL query construction, parameter binding, and result streaming. Supports querying published datasources by ID with field-level metadata discovery via the Metadata API (GraphQL). Results are returned as structured data (rows/columns) that AI systems can reason about and present to users. The tool framework abstracts VizQL complexity, allowing agents to query Tableau data without understanding VizQL syntax.

Implements HTTP server deployment mode using Express.js and @modelcontextprotocol/sdk's StreamableHTTPServerTransport. The server listens on a configurable port (default 3000) and accepts MCP requests via HTTP POST. Each request is routed to the appropriate tool handler, which executes and returns results. The implementation supports session management for stateful operations (e.g., OAuth token refresh). HTTP transport enables remote client connections and cloud deployment scenarios. The server can be deployed as a Docker container or standalone binary with HTTP transport.

Provides pre-built Docker images and Single Executable Application (SEA) binaries for easy deployment without Node.js installation. The Docker image includes all dependencies and can be run with environment variables for configuration. The SEA binary is a self-contained executable that bundles Node.js and the MCP server, enabling deployment to systems without Node.js. Both deployment methods support the same environment-based configuration system. Build system (TypeScript compilation, bundling) produces both Docker images and SEA binaries from the same source code.

Implements a toolFactories pattern where each tool group (datasource, workbook, view, content, pulse) is defined as a factory function that returns Tool instances. The Server class iterates over toolFactories and instantiates tools, optionally filtering based on INCLUDE_TOOLS/EXCLUDE_TOOLS environment variables. Each Tool wraps a callback that calls into the RestApi layer. The pattern enables modular tool organization, selective tool registration, and easy addition of new tools without modifying the Server class. Tool implementations are decoupled from the MCP server framework.

Implements list-workbooks, list-views, and get-view-data tools that enumerate Tableau workbooks and views accessible to the authenticated user via REST API calls. The tools return structured metadata (workbook name, owner, description, view names, last modified timestamp) that agents can use to discover relevant content. get-view-data retrieves the underlying data from a specific view by calling REST API endpoints that return view data as structured rows. The implementation filters results based on user permissions automatically; agents see only content they have access to.

Implements search-content tool that queries Tableau's full-text search index via REST API to find workbooks, views, datasources, and metrics by keyword. The tool accepts search terms and optional content type filters, returning ranked results with metadata (name, owner, description, content type, URL). Search is performed server-side using Tableau's built-in indexing; results are automatically filtered by user permissions. The tool enables agents to locate relevant Tableau content without enumerating all available items, improving performance for large Tableau instances.

Exposes list-metric-definitions, list-metrics, generate-insight-bundle, and generate-insight-brief tools that integrate with Tableau Pulse (Tableau's AI-powered analytics feature). The tools allow agents to enumerate published metrics, retrieve metric values and trends, and request AI-generated insights about metric behavior. generate-insight-bundle returns comprehensive analysis (anomalies, trends, comparisons), while generate-insight-brief provides concise summaries. The implementation calls Tableau's Pulse API and REST API endpoints, abstracting the complexity of insight generation and metric aggregation. Results include natural language explanations and supporting data.

Implements a pluggable authentication system supporting four credential types: Personal Access Token (PAT), Connected App JWT (direct-trust), User Attribute Token (UAT), and OAuth 2.1. The Config class reads authentication credentials from environment variables and initializes the appropriate auth handler. Each auth method produces a valid Tableau session token used for all downstream REST API and VizQL calls. OAuth 2.1 flow includes authorization code exchange, token refresh, and session management. The system abstracts auth complexity; tools use authenticated sessions without knowing the underlying auth method.

Implements a Config class that reads all server configuration from environment variables (TABLEAU_SERVER_URL, TABLEAU_SITE_NAME, INCLUDE_TOOLS, EXCLUDE_TOOLS, logging settings, etc.). The configuration system supports tool filtering via INCLUDE_TOOLS (whitelist) and EXCLUDE_TOOLS (blacklist) environment variables, enabling selective capability exposure without code changes. Configuration is validated at startup; invalid or missing required variables cause startup failure with clear error messages. The system supports multiple deployment modes (local, Docker, SEA) by reading the same environment variables.

Implements a logging system that captures MCP server events, API calls, authentication flows, and errors with configurable verbosity (LOG_LEVEL environment variable). Logs are structured (JSON format) for easy parsing by log aggregation systems. The system logs tool invocations, API request/response metadata, authentication events, and performance metrics (latency, result sizes). Telemetry can be sent to external systems (e.g., Datadog, Splunk) via log shipping. Logs are written to stdout/stderr, making them compatible with container logging drivers and log aggregation platforms.

Implements get-view-image tool that renders Tableau views as static images (PNG, PDF) via REST API. The tool accepts a view ID and optional parameters (size, format, filters) and returns the rendered image. The implementation calls Tableau's view export endpoints, which render the view server-side using Tableau's rendering engine. Images can be embedded in reports, sent via email, or displayed in chat interfaces. The tool abstracts rendering complexity; agents request images without understanding Tableau's rendering pipeline.

Implements get-datasource-metadata and list-fields tools that query Tableau's GraphQL Metadata API to discover datasource structure (tables, fields, field types, relationships). The tools return comprehensive metadata including field names, data types, aggregation capabilities, and field descriptions. The implementation uses GraphQL queries to fetch metadata efficiently; results are structured for agent consumption. Agents can use this metadata to understand datasource schema before constructing queries, enabling intelligent query construction and validation.