List Workbooks
Retrieves a list of workbooks on a Tableau site, including their metadata such as name, description,
and information about the views contained in each workbook. Supports optional filtering via
field:operator:value expressions (e.g. name:eq:Superstore) for precise, flexible workbook
discovery. Use this tool when a user requests to list, search, or filter Tableau workbooks on a site.
APIs called
This tool talks to the Tableau REST API (Tableau Cloud or Server) to list the site's workbooks,
then optionally enriches each result with datasource lineage from the Metadata API (GraphQL).
The MCP-layer OAuth gate requires tableau:content:read (cited per operation below) plus
tableau:mcp_site_settings:read to read per-site MCP configuration overrides (e.g.
MAX_RESULT_LIMIT,
DISABLE_METADATA_API_REQUESTS)
when MCP site settings are enabled.
- List the site's workbooks. Returns the workbooks visible to the caller, applying the
filterexpression when provided. The tool paginates automatically, repeatedly calling the endpoint until all matching workbooks are retrieved or thelimitis reached.GET /api/{version}/sites/{siteId}/workbooks— query the workbooks for the site. Issued against the Tableau REST API; requires thetableau:content:readOAuth scope. Query Workbooks for Site
- Enrich workbooks with datasource lineage. Best-effort follow-up that adds published-datasource
lineage metadata to the listed workbooks. Skipped when there are no workbooks or when metadata
requests are disabled via
DISABLE_METADATA_API_REQUESTS.POST /api/metadata/graphql— query workbook-to-datasource lineage. Issued against the Metadata API (GraphQL); requires thetableau:content:readOAuth scope. Tableau Metadata API
Optional arguments
filter
A filter expression as defined in the Tableau REST API Workbooks filter fields. Combine multiple expressions by separating them with commas.
Example: name:eq:Superstore
Supported filter fields and operators
| Field | Operators |
|---|---|
| createdAt | eq, gt, gte, lt, lte |
| contentUrl | eq, in |
| displayTabs | eq |
| favoritesTotal | eq, gt, gte, lt, lte |
| hasAlerts | eq |
| hasExtracts | eq |
| name | eq, in |
| ownerDomain | eq, in |
| ownerEmail | eq, in |
| ownerName | eq, in |
| projectName | eq, in |
| sheetCount | eq, gt, gte, lt, lte |
| size | eq, gt, gte, lt, lte |
| subscriptionTotal | eq, gt, gte, lt, lte |
| tags | eq, in |
| updatedAt | eq, gt, gte, lt, lte |
pageNumber
Which 1000-item page to fetch (1-based, default 1).
limit
The maximum number of workbooks to return. The tool will return at most this many workbooks. The
effective cap is the tighter of this argument and the server-configured
MAX_RESULT_LIMIT.
Example: 2000
See also: MAX_RESULT_LIMIT
Notes and caveats
- The set of workbooks that can be returned may be limited by the server configuration. When an allow-list of projects, workbooks, or tags is configured, results outside it are filtered out, so the tool can return an empty list even though workbooks exist on the site.
- Lineage enrichment is best-effort: if the Metadata API request fails, the tool logs a warning and returns the workbooks without the added lineage metadata rather than failing the call.
Example result
[
{
"id": "222ea993-9391-4910-a167-56b3d19b4e3b",
"name": "Superstore",
"webpageUrl": "https://10ax.online.tableau.com/#/site/mcp-test/workbooks/1412200",
"contentUrl": "Superstore",
"project": {
"name": "Samples",
"id": "cbec32db-a4a2-4308-b5f0-4fc67322f359"
},
"showTabs": true,
"defaultViewId": "9460abfe-a6b2-49d1-b998-39e1ebcc55ce",
"tags": {}
}
]
Related
get-workbook— retrieve a single workbook's details and view usage statistics
Worked example
The response fields are:
data: the workbooks on the requested page (at most 1000, or fewer whenlimitor a server cap applies).totalAvailable: the number of workbooks available for pagination, never more than a server cap. Your ownlimitargument does not affect this value.mcp.resultInfo: present only when a server cap hides workbooks:{ returnedCount, truncated: true, truncationReason: "admin-cap" }.returnedCountis the number of items indata.
Arguments no longer accepted
These arguments were described on an earlier page and are not accepted by the current tool.
pageSize
The value of the page-size argument provided to the
Query Workbooks for Site
REST API. The tool automatically performs pagination and will repeatedly call the REST API until
either all workbooks are retrieved or the limit argument has been reached. The pageSize argument
determines how many workbooks to return in each call. You may want to provide a larger value if you
know in advance that you have more than 100 workbooks to retrieve.
Example: 1000