How do I set up dbt MCP?

Install `uv`, provide the dbt project and warehouse context required by the server, then add the local process to your MCP client.

Can dbt MCP connect to dbt Cloud?

The catalog entry is a local dbt MCP server. A dbt Cloud connection needs the project and credentials supported by the installed implementation rather than assuming every Cloud API is available.

Can dbt MCP work with dbt Core?

Yes, when the local project and runtime match what the server expects. Configure the dbt project on the same machine that starts the MCP process.

Can dbt MCP inspect model dependencies?

Model exploration is one of the catalog entry's stated uses. The live function list defines the dependency and metadata operations available.

Can dbt MCP run a dbt build?

Build execution depends on the functions returned by the running server. Review the live function list before allowing an agent to trigger warehouse work.

Can dbt MCP read the semantic layer?

Semantic-layer metadata is part of the entry's stated scope. The connected server determines which metrics, models and arguments it exposes.

Can dbt MCP work with Cursor?

Add the local server to Cursor's MCP settings and make the dbt project and warehouse environment available to the process.

Can dbt MCP work in VS Code?

A VS Code MCP client can use the local server when it starts the process with `uv` and the correct dbt project context. The editor does not replace the dbt runtime.

dbt MCP: Models, Builds and the Semantic Layer

What it does

dbt MCP gives an agent access to the transformation project behind a warehouse question. It can inspect models and build state instead of treating the warehouse as a black box.

Explore dbt models and dependencies.
Read model and column metadata.
Inspect or run builds when supported.
Work with semantic-layer information.
Keep project paths and warehouse credentials in the runtime.

Available functions

cancel_job_run Cancel a currently running or queued dbt run. This tool allows you to stop a run that is currently executing or waiting in the queue. ## Returns Updated run object showing the cancelled status and timing information. ## Run States That Can Be Cancelled - **Queued (1)**: Run is waiting to start - **Starting (2)**: Run is initializing - **Running (3)**: Run is currently executing ## Use Cases - Stop long-running jobs that are no longer needed - Cancel jobs that were triggered by mistake - Free up run slots for higher priority jobs - Stop runs that are stuck or hanging - Emergency cancellation during incidents ## Important Notes - Once cancelled, a run cannot be resumed - Partial work may have been completed before cancellation - Artifacts from cancelled runs may not be available - Use the retry functionality if you need to re-run after cancellation ## Example Usage ```json { "run_id": 789 } ``` ## Response Returns the updated run object with: - Status changed to cancelled (30) - Cancellation timestamp - Final execution timing - Any artifacts that were generated before cancellation

Arguments

run_id required: integer The dbt job run ID

get_all_macros Get the name, description, and package name of all dbt macros in the environment. Macros are reusable pieces of Jinja SQL that can be called from models, tests, and other macros. Usage patterns: 1. Discover available packages first: `get_all_macros(return_package_names_only=True)` 2. Then get macros for specific packages: `get_all_macros(package_names=['my_project'])` Note: - dbt-labs first-party packages are excluded by default. These are packages maintained directly by dbt Labs from the dbt-labs/dbt-adapters monorepo: - dbt (dbt-core) - dbt_postgres - dbt_redshift - dbt_snowflake - dbt_bigquery - dbt_spark - dbt_athena - Community packages (dbt_utils, dbt_expectations, dbt_date) are included - Partner-maintained adapters (dbt_databricks, dbt_trino, dbt_synapse) are included - All project-specific macros are included Returns: - When return_package_names_only=False (default): List of macros with name, uniqueId, description, packageName - When return_package_names_only=True: List of unique package names (strings) Returns one source page in `result`, with `pagination.has_more` and `pagination.next_cursor`. Pass the next cursor as `after` with the same filters. `limit` defaults to 50 and is capped at 100. Local filtering may leave an empty page with more pages available.

Arguments

after: Cursor returned by the previous page's next_cursor; keep filters unchanged. Default: null
include_default_dbt_packages: boolean When true, include default dbt Labs core/adapter macro packages Default: false
limit: integer Maximum items in this page (1–100, default 50). Default: 50
package_names: Filter macros to these package names (e.g. `my_project`, `dbt_utils`) Default: null
return_package_names_only: boolean When true, return only distinct package names (use to discover packages before filtering) Default: false

get_all_models Get a page of dbt model names and descriptions in the environment. Returns one source page in `result`, with `pagination.has_more` and `pagination.next_cursor`. Pass the next cursor as `after` with the same filters. `limit` defaults to 50 and is capped at 100. Local filtering may leave an empty page with more pages available.

Arguments

after: Cursor returned by the previous page's next_cursor; keep filters unchanged. Default: null
limit: integer Maximum items in this page (1–100, default 50). Default: 50

get_all_sources Get the name, description, and metadata of all dbt sources in the environment. Sources represent external data tables that your dbt models build upon. Note: - source_names correspond to the top-level source grouping in the source YML config - unique_ids have the form `source.{YOUR-DBT-PROJECT}.{SOURCE-NAME}.{SOURCE-TABLE}` Returns information including: - name: The table name within the source - uniqueId: The unique identifier for this source table - identifier: The underlying table identifier in the warehouse - description: Description of the source table - sourceName: The source name (e.g., 'raw_data', 'external_api') - database: Database containing the source table - schema: Schema containing the source table - resourceType: Will be 'source' - freshness: Real-time freshness status from production including: - maxLoadedAt: When the source was last loaded - maxLoadedAtTimeAgoInS: How long ago the source was loaded (in seconds) - freshnessStatus: Current freshness status (e.g., 'pass', 'warn', 'error') Returns one source page in `result`, with `pagination.has_more` and `pagination.next_cursor`. Pass the next cursor as `after` with the same filters. `limit` defaults to 50 and is capped at 100. Local filtering may leave an empty page with more pages available.

Arguments

after: Cursor returned by the previous page's next_cursor; keep filters unchanged. Default: null
limit: integer Maximum items in this page (1–100, default 50). Default: 50
source_names: Filter by top-level source names from the project `sources:` YAML (e.g. `raw_data`, `external_api`) Default: null
unique_ids: Filter by fully qualified source table unique IDs (`source.<project>.<source_name>.<table>`) Default: null

get_dimension_values <instructions> Get the distinct values for a given dimension, optionally scoped to specific metrics. Use this tool to discover what values exist for a dimension before building a `where` filter in `query_metrics`. For example, to filter by country you first call this tool to see which country values exist, then use those values in the `where` clause. If the response includes `truncated: true`, there are more values than the current `limit`. Increase `limit` to retrieve more, or add `metrics` to narrow the scope. </instructions> <examples> <example> Question: "I want to filter revenue for a specific country — what countries are available?" Thinking step-by-step: - The user wants to know valid values for a country dimension - I should scope to the "revenue" metric for accurate results Parameters: dimension="customer__country" metrics=["revenue"] limit=100 </example> <example> Question: "What are the possible order statuses?" Thinking step-by-step: - The user wants all distinct values for an order status dimension - No specific metric context needed Parameters: dimension="order__status" metrics=null limit=100 </example> </examples>

Arguments

dimension required: string The dimension name to retrieve values for (e.g. `customer__country`, `order__status`)
limit: integer Maximum number of distinct values to return (default 100). If the result is truncated, the response `truncated` field will be True — increase this limit to retrieve more values. Default: 100
metrics: Metric names from list_metrics to query or inspect Default: null

get_dimensions <instructions> Get the dimensions for specified metrics Note: `metric_time` is a standard time dimension available on most metrics. You do not need to call this tool just to confirm time dimensions exist — call it only when you need categorical dimensions or specific granularity details. If this tool returns no results, proceed to query directly using `metric_time`. Dimensions are the attributes, features, or characteristics that describe or categorize data. Each dimension includes a metadata field containing config.meta from semantic model YAML files. The metadata contains fields relevant to the semantic models. </instructions> <examples> <example> Question: "I want to analyze revenue trends - what dimensions are available?" Thinking step-by-step: - Using list_metrics(), I find "revenue" is available - Now I can get the dimensions for this metric - The search parameter is not needed here since the user is interested in all available dimensions. Parameters: metrics=["revenue"] search=null </example> <example> Question: "Are there any time-related dimensions for my sales metrics?" Thinking step-by-step: - Using list_metrics(), I find "total_sales" and "average_order_value" are available - The user is interested in time dimensions specifically - I should use the search parameter to filter for dimensions with "time" in the name - This will narrow down the results to just time-related dimensions Parameters: metrics=["total_sales", "average_order_value"] search="time" </example> </examples> Returns one source page in `result`, with `pagination.has_more` and `pagination.next_page`. Pass the next page as `page_num` with the same filters and `page_size` (default 50, maximum 100). Local filtering may leave an empty page with more pages available. Restart at page 1 if you reduce the page size after a size-limit error.

Arguments

metrics required: array Metric names from list_metrics to query or inspect
page_num: integer One-based page number; keep filters and page size unchanged. Default: 1
page_size: integer Maximum items in this page (1–100, default 50). Default: 50
search: Filter dimensions by substring match on name (omit to return all for these metrics) Default: null

get_entities <instructions> Get the entities for specified metrics Entities are real-world concepts in a business such as customers, transactions, and ad campaigns. Analysis is often focused around specific entities, such as customer churn or annual recurring revenue modeling. </instructions> <examples> <example> Question: "I want to analyze revenue - what entities are available?" Thinking step-by-step: - Using list_metrics(), I find "revenue" is available - Now I can get the entities for this metric - The search parameter is not needed here since the user is interested in all available entities. Parameters: metrics=["revenue"] search=null </example> <example> Question: "Are there any customer-related entities for my sales metrics?" Thinking step-by-step: - Using list_metrics(), I find "total_sales" and "average_order_value" are available - The user is interested in customer entities specifically - I should use the search parameter to filter for entities with "customer" in the name - This will narrow down the results to just customer-related entities Parameters: metrics=["total_sales", "average_order_value"] search="customer" </example> </examples> Returns one source page in `result`, with `pagination.has_more` and `pagination.next_page`. Pass the next page as `page_num` with the same filters and `page_size` (default 50, maximum 100). Local filtering may leave an empty page with more pages available. Restart at page 1 if you reduce the page size after a size-limit error.

Arguments

metrics required: array Metric names from list_metrics to query or inspect
page_num: integer One-based page number; keep filters and page size unchanged. Default: 1
page_size: integer Maximum items in this page (1–100, default 50). Default: 50
search: Filter entities by substring match on name (omit to return all for these metrics) Default: null

get_exposure_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_exposures Get the id, name, description, and url of all exposures in the dbt environment. Exposures represent downstream applications or analyses that depend on dbt models. Returns information including: - uniqueId: The unique identifier for this exposure taht can then be used to get more details about the exposure - name: The name of the exposure - description: Description of the exposure - url: URL associated with the exposure Returns one source page in `result`, with `pagination.has_more` and `pagination.next_cursor`. Pass the next cursor as `after` with the same filters. `limit` defaults to 50 and is capped at 100. Local filtering may leave an empty page with more pages available.

Arguments

after: Cursor returned by the previous page's next_cursor; keep filters unchanged. Default: null
limit: integer Maximum items in this page (1–100, default 50). Default: 50

get_job_details Get detailed information for a specific dbt job. This tool retrieves comprehensive job configuration including execution settings, triggers, and scheduling information. ## Returns Job object with detailed configuration including: - Job metadata (ID, name, description, type) - Environment and project associations - Execute steps (dbt commands to run) - Trigger configuration (schedule, webhooks, CI) - Execution settings (timeout, threads, target) - dbt version overrides - Generate docs and sources settings - Most recent run information (if requested) ## Use Cases - Debug job configuration issues - Understand job execution settings - Review scheduling and trigger configuration - Check dbt commands and execution steps - Audit job settings across projects - Get recent run status for monitoring ## Job Types - **ci**: Continuous integration jobs - **scheduled**: Regularly scheduled jobs - **other**: Manual or API-triggered jobs - **merge**: Jobs triggered on merge events ## Example Usage ```json { "job_id": 456 } ```

Arguments

job_id required: integer The dbt job definition ID

get_job_run_artifacts Get a specific artifact file from a dbt job run. This tool retrieves the content of a specific artifact file generated during run execution, such as manifest.json, catalog.json, or run_results.json. ## Common Artifact Paths - **manifest.json**: Complete dbt project metadata, models, and lineage - **catalog.json**: Table and column documentation with statistics - **run_results.json**: Execution results, timing, and status information - **sources.json**: Source freshness check results - **logs/dbt.log**: Complete execution logs Use `list_job_run_artifacts` first to see which artifacts are available for a run. ## Unsupported Paths Paths under `index/` and `metadata/` are dbt docs v2 / dbt Information Schema Parquet files. They are binary and cannot be returned as text — calling this tool with those paths will return an error. Support for querying them is not yet available. ## Output Options - **Default (no filter)**: Returns content inline for artifacts under 500 KB. Large artifacts (like a full `manifest.json`) are not returned inline — instead you get a short guidance message telling you to re-call with a `jq_filter` to extract just the part you need. - **jq_filter set**: Applies a jq filter and returns results as a JSON array inline. Works in both local and remote deployments and is the primary way to read large artifacts like `manifest.json`. Only valid for JSON artifacts; returns `[]` on no match. Filtered output is also capped at 500 KB — use aggregation filters (e.g. `keys`, `length`, `select()`) if you hit the limit. ## jq Filter Reference **Output shape:** Results are always a JSON array — one element per value the filter emits. A single-match filter returns `[{...}]`; no match returns `[]`. Read `result[0]` to unwrap a single value. **Double-wrap:** Filters that construct a jq array (`[...]`, `group_by | map(...)`) produce `[[...]]`. Prefer iterator-style filters (`.results[] | select(...)`) for flat output. **Prefer aggregation over enumeration on large manifests** — enumerating all matching nodes can produce hundreds of kilobytes and exceed the 500 KB output cap: ``` [.nodes | to_entries[] | select(.value.config.materialized == "table")] | length ``` **Structural filters are fast; node-traversal filters are slow.** `keys` and `.metadata` touch only the top-level object and return quickly. Any filter that iterates `.nodes` values (even an aggregation that returns a small result) scans the entire manifest, and on a very large project can take tens of seconds and approach the evaluation timeout. Start with `keys`/`.metadata` to orient, then reach for a single targeted traversal rather than several. **Top-level keys by artifact:** - `run_results.json` — `.results[]` (array of node results with `.status`, `.unique_id`, `.execution_time`, `.message`) - `manifest.json` — `.nodes` (object keyed by `"model.project.name"`), `.sources`, `.exposures`, `.metrics` - `catalog.json` — `.nodes["model.project.name"].columns`, `.nodes["model.project.name"].stats` ## Step Selection By default, artifacts from the **last step** are returned — but this is often not what you want. Two important caveats: 1. **Docs generation footgun**: Jobs that include a `dbt docs generate` step will have that step's compilation results as the default artifact, not the model execution results. `run_results.json` without a `step` will show all nodes as successful even when an earlier model run step had failures. 2. **Infrastructure steps produce no artifacts**: Steps like git clone, profile creation, and `dbt deps` do not write a `run_results.json`. Requesting an artifact from one of those steps raises a not-found error. The `step` parameter refers only to steps that run a dbt command (`dbt build`, `dbt run`, `dbt test`, `dbt docs generate`, etc.). Always use `get_job_run_details` to inspect step names and statuses before specifying `step`, so you can identify which step index corresponds to the actual model execution. - Step indexing starts at 1 for the first step

Arguments

artifact_path required: string Path to the artifact file (e.g. 'manifest.json', 'run_results.json', 'catalog.json'). Use list_job_run_artifacts to see available paths.
jq_filter: A jq filter expression to apply to the artifact before returning. Only valid for JSON artifacts. Required to read large artifacts (e.g. manifest.json) that are too big to return inline. Results are always returned as a JSON array inline regardless of artifact size — if the filter matches nothing, '[]' is returned. Examples: '.results[] | select(.status == "error")' to extract failures; '.nodes | keys[]' to list all node IDs; '.metadata' to inspect artifact metadata. Default: null
run_id required: integer The dbt job run ID
step: Step number to retrieve the artifact from (1-indexed). Defaults to the last step when omitted. Only dbt command steps (dbt build, dbt run, dbt test, dbt docs generate) produce artifacts — infrastructure steps (git clone, profile creation, dbt deps) will raise a not-found error. Default: null

get_job_run_details Get detailed information for a specific dbt job run. This tool retrieves comprehensive run information including execution details, steps, and artifacts. ## Returns Run object with detailed execution information including: - Run metadata (ID, status, timing information) - Job and environment details - Git branch and SHA information - Execution steps and their status - Artifacts and logs availability - Trigger information and cause - Performance metrics and timing ## Use Cases - Monitor run progress and status - Debug failed runs with detailed logs - Review run performance and timing - Check artifact generation status - Audit run execution details - Troubleshoot run failures ## Example Usage ```json { "run_id": 789 } ``` ```json { "run_id": 789 } ``` ## Response Information The detailed response includes timing, status, and execution context to help with monitoring and debugging dbt job runs.

Arguments

run_id required: integer The dbt job run ID

get_job_run_error Get focused error and/or warning information for a dbt job run. This tool retrieves and analyzes job runs to provide concise, actionable error and warning details optimized for troubleshooting and monitoring. Instead of verbose run details, it returns structured information with minimal token usage. ## Returns ### Default Behavior (errors only) Structured error information with `failed_steps` containing a list of failed step details: - failed_steps: List of failed steps, each containing: - target: The dbt target environment where the failure occurred - step_name: The failed step that caused the run to fail - finished_at: Timestamp when the failed step completed - results: List of specific error details, each with: - unique_id: Model/test unique identifier (nullable) - relation_name: Database relation name or "No database relation" - message: Error message - compiled_code: Raw compiled SQL code (nullable) - truncated_logs: Raw truncated debug log output (nullable) NOTE: The "truncated_logs" key only populates if there is no `run_results.json` artifact to parse after a job run error. ### When include_warnings=True Returns both error information (as above) plus a `warnings` object containing: - has_warnings: Boolean indicating if any warnings were found - warning_steps: List of successful steps containing warnings - log_warnings: List of warnings extracted from logs - summary: Aggregate warning counts ### When warning_only=True Returns only warning information (same structure as the `warnings` object above): - has_warnings: Boolean indicating if any warnings were found - warning_steps: List of successful steps containing warnings, each with: - target: The dbt target environment - step_name: The step that generated warnings - finished_at: Timestamp when the step completed - results: List of specific warning details, each with: - unique_id: Model/test/source unique identifier - relation_name: Database relation name or source name - message: Warning message describing the issue - status: Always "warn" to distinguish from errors - compiled_code: Raw compiled SQL code (optional, for test warnings) - log_warnings: List of warnings extracted directly from logs (no unique_id) - summary: Aggregate warning counts: - total_warnings: Total number of warnings found - test_warnings: Number of test warnings (tests with `severity: warn`) - freshness_warnings: Number of source freshness warnings - log_warnings: Number of warnings extracted from logs ## Example Usage ### Get errors only (default) ```json { "run_id": 789 } ``` ### Get errors with warnings ```json { "run_id": 789, "include_warnings": true } ``` ### Get warnings only ```json { "run_id": 789, "warning_only": true } ```

Arguments

include_warnings: boolean If true, include warning analysis together with error details Default: false
run_id required: integer The dbt job run ID
warning_only: boolean If true, return only warning analysis (e.g. for successful runs with warnings) Default: false

get_lineage Retrieves the lineage graph for a dbt resource. Returns the subgraph of nodes connected to the specified resource, including both upstream dependencies (ancestors) and downstream dependents (descendants). **Returns:** A structured `LineageGraph` object: - `root_id`: the `unique_id` the lineage was computed relative to (the target node). - `nodes`: the connected nodes, each with: - `unique_id`: the resource's unique identifier - `name`: the resource name - `resource_type`: the type of resource (Model, Source, etc.) - `edges`: the dependency edges, each with `source` and `target` `unique_id`s, where `source` is an upstream parent of `target` (data flows `source` → `target`). - `omitted_node_count`: number of nodes matching the requested filters excluded by `limit` (`0` means none were excluded by the limit). The target node (`root_id`) is present in `nodes` for `direction="both"` (the default). For `direction="upstream"`/`"downstream"` the target is excluded, so `root_id` may not appear in `nodes`. Call `get_lineage(unique_id=...)` to retrieve up to 100 nodes from the target and its immediate parents and children (the default `depth=1`). Use `direction` to narrow the response to one side of the graph and reduce payload size: - `direction="upstream"`: ancestors only — excludes the target node and descendants - `direction="downstream"`: descendants only — excludes the target node and ancestors - `direction="both"` (default): the target node plus both ancestors and descendants Use `limit` to bound the number of returned nodes (default `100`). The closest nodes are returned first. If `omitted_node_count` is positive, increase the limit or narrow `direction` or `types` to retrieve more lineage. The limit applies to the returned graph; the Discovery API query still fetches the environment's full lineage. Use `depth=1` with `direction="upstream"` or `"downstream"` for direct parents or children. The target is excluded, and `omitted_node_count` shows when the limit excluded any results. **Example Response:** ```json { "type": "lineage_graph", "root_id": "model.customers", "nodes": [ {"unique_id": "model.customers", "name": "customers", "resource_type": "Model"}, {"unique_id": "model.stg_customers", "name": "stg_customers", "resource_type": "Model"}, {"unique_id": "source.raw.users", "name": "users", "resource_type": "Source"} ], "edges": [ {"source": "source.raw.users", "target": "model.stg_customers"}, {"source": "model.stg_customers", "target": "model.customers"} ], "omitted_node_count": 0 } ``` **Usage Examples:** ```python # Get lineage (immediate parents and children — default depth of 1) get_lineage(unique_id="model.analytics.customers") # Get lineage filtered to only models and sources get_lineage(unique_id="model.analytics.customers", types=["Model", "Source"]) # Get deeper lineage for comprehensive analysis get_lineage(unique_id="model.analytics.customers", depth=10) # Traverse all depths (returning up to the node limit) get_lineage(unique_id="model.analytics.customers", depth=0) # Get only upstream dependencies (ancestors), e.g. for dependency tracking get_lineage(unique_id="model.analytics.customers", direction="upstream") # Get only downstream dependents (descendants), e.g. for impact analysis get_lineage(unique_id="model.analytics.customers", direction="downstream") ``` **Traversing the Graph:** Relationships are explicit in `edges` (`source` → `target`, parent → child). **Finding Upstream Dependencies (Parents):** the parents of a node are the `edges` whose `target` is that node — read their `source`. **Finding Downstream Dependents (Children):** the children of a node are the `edges` whose `source` is that node — read their `target`. **Understanding the Results:** - The target node is included only when `direction="both"` (the default); it is excluded for `direction="upstream"`/`"downstream"` - All returned nodes are connected to the target (no disconnected nodes) - To include every resource type, omit the `types` parameter - To reduce payload size, specify relevant `types` **Common Use Cases:** 1. **Impact Analysis**: "What will break if I change this model?" - Follow `edges` downstream from the target (edges where `source` is the target) 2. **Dependency Tracking**: "What does this model depend on?" - Follow `edges` upstream to the target (edges where `target` is the target node) 3. **Data Lineage**: "Show the data flow for this entity" - Use `nodes` and `edges` to build the returned graph; increase `limit` if nodes were omitted 4. **Finding Tests**: "What tests exist for this model and its dependencies?" - Filter `nodes` where `resource_type == "Test"`

Arguments

depth: integer The depth of the lineage graph to return. Controls how many levels to traverse from the target node. A depth of 1 returns only direct parents/children. A depth of 0 returns the entire lineage graph. Default: 1
direction: Which direction(s) of the graph to return, relative to the target node: `upstream` (ancestors/parents only), `downstream` (descendants/children only), or `both` (default). Narrowing to one direction reduces response size. Default: both
limit: integer Maximum number of nodes to return. The closest nodes are returned first in breadth-first order. Default: 100
types: List of resource types to include in lineage results. If not provided, includes all types. Valid types: Model, Source, Seed, Snapshot, Exposure, Metric, SemanticModel, SavedQuery, Test. Default: null
unique_id required: string Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`).

get_macro_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_mart_models Get the name and description of all mart models in the environment. A mart model is part of the presentation layer of the dbt project. It's where cleaned, transformed data is organized for consumption by end-users, like analysts, dashboards, or business tools. Returns one source page in `result`, with `pagination.has_more` and `pagination.next_cursor`. Pass the next cursor as `after` with the same filters. `limit` defaults to 50 and is capped at 100. Local filtering may leave an empty page with more pages available.

Arguments

after: Cursor returned by the previous page's next_cursor; keep filters unchanged. Default: null
limit: integer Maximum items in this page (1–100, default 50). Default: 50

get_metrics_compiled_sql <instructions> Gets compiled SQL for given metrics and dimensions/entities from the dbt Semantic Layer. This tool generates the underlying SQL that would be executed for a given metric query by the `query_metrics` tool, without actually running the query. This is useful for understanding what SQL is being generated, debugging query issues, or getting SQL to run elsewhere. To use this tool, you must first know about specific metrics, dimensions and entities to provide. You can call the list_metrics, get_dimensions, and get_entities tools to get information about which metrics, dimensions, and entities to use. When using the `group_by` parameter, ensure that the dimensions and entities you specify are valid for the given metrics. Time dimensions can include grain specifications (e.g., MONTH, DAY, YEAR). The tool will return the compiled SQL that the dbt Semantic Layer would generate to calculate the specified metrics with the given groupings. Don't call this tool if the user's question cannot be answered with the provided metrics, dimensions, and entities. Instead, clarify what metrics, dimensions, and entities are available and suggest a new question that can be answered and is approximately the same as the user's question. This tool is particularly useful when: - Users want to see the underlying SQL for a metric calculation - Debugging complex metric definitions - Understanding how grouping affects the generated SQL - Getting SQL to run in other tools or systems </instructions> Returns the compiled SQL as a string, or an error message if the compilation fails.

Arguments

group_by: Group by dimensions, time dimensions, or entities; each item has `name`, `type` (`"dimension"`, `"time_dimension"`, or `"entity"`), and optional `grain` for time dimensions Default: null
limit: Maximum number of results to return Default: null
metrics required: array Metric names from list_metrics to query or inspect
order_by: Sort keys; each item has `name`, `descending` (default false), and optional `grain` for time dimensions (overrides the grain from group_by; falls back to the matching group_by grain when omitted); items may be metric names or group_by fields Default: null
where: Semantic Layer filter; use {{ Dimension('name') }}, {{ TimeDimension('name', 'grain') }}, {{ Entity('name') }}; dates as yyyy-mm-dd Default: null

get_model_children **DEPRECATED — use `get_lineage` instead.** This tool will be removed in a future release. Call get_lineage(unique_id=..., depth=1, direction="downstream") — it requires unique_id (not name); direction="downstream" returns children up to the node limit. Check omitted_node_count for more.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_model_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_model_health <instructions> Retrieves information about the health of a dbt model, including the last time it ran, the last test execution status, and whether the upstream data for the model is fresh. IMPORTANT: Use uniqueId when available. - Using uniqueId guarantees the correct model is retrieved - Using only name may return incorrect results or fail entirely - If you obtained models via get_all_models(), you should always use the uniqueId from those results ASSESSING MODEL HEALTH: For all of the below, summarize whether the model is healthy, questionable, or unhealthy. Only provide more details when asked. - for the model executionInfo, if the lastRunStatus is "success" consider the model healthy - for the test executionInfo, if the lastRunStatus is "success" consider the model healthy - for the models parents: -- check the modelexecutionInfo, snapshotExecutionInfo, and seedExecutionInfo. If the lastRunStatus is "success" consider the model healthy. If the lastRunStatus is "error" consider the model unhealthy. -- if the parent node is a SourceAppliedStateNestedNode: --- If the freshnessStatus is "pass", consider the model healthy --- If the freshnessStatus is "fail", consider the model unhealthy --- If the freshnessStatus is null, consider the model health questionable --- If the freshnessStatus is "warn", consider the model health questionable </instructions> <examples> 1. PREFERRED METHOD - Using uniqueId (always use this when available): get_model_health(uniqueId="model.my_project.customer_orders") 2. FALLBACK METHOD - Using only name (only when uniqueId is unknown): get_model_health(name="customer_orders") </examples>

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_model_parents **DEPRECATED — use `get_lineage` instead.** This tool will be removed in a future release. Call get_lineage(unique_id=..., depth=1, direction="upstream") — it requires unique_id (not name); direction="upstream" returns parents up to the node limit. Check omitted_node_count for more.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_model_performance <instructions> Retrieve execution performance metrics for a dbt model from historical runs. This tool queries the Discovery API to fetch model execution data including: - Execution time (duration in seconds) - Run status (success, error, skipped) - Execution timestamps - Associated job run IDs - Optional: Test execution history (when include_tests=True) Use this to: - Analyze model performance trends over time - Identify performance regressions - Optimize slow-running models - Debug execution issues - Monitor test execution alongside model runs The `unique_id` parameter is strongly preferred over `name` for deterministic lookups, especially in projects with multiple packages. If a name matches multiple models, the tool will raise an error and ask for a `unique_id`. Results are always returned as an array (possibly empty), sorted newest-first. - When `num_runs=1` (default), the array has at most one element (the latest run). - When `num_runs > 1`, the array includes up to `num_runs` historical runs. When `include_tests=True`, each run will include a `tests` array containing: - Test name - Test status (pass, fail, warn, error, skipped) - Test execution time (duration in seconds) Example unique_id format: model.analytics.stg_orders </instructions> <examples> 1. PREFERRED METHOD - Get latest run performance using unique_id: get_model_performance(unique_id="model.analytics.stg_orders") 2. Analyze performance trend over last 10 runs: get_model_performance(unique_id="model.analytics.fct_orders", num_runs=10) 3. Get performance with test execution history: get_model_performance(unique_id="model.analytics.stg_orders", num_runs=5, include_tests=True) 4. FALLBACK METHOD - Using only name (only when unique_id is unknown): get_model_performance(name="stg_orders", num_runs=5) </examples>

Arguments

include_tests: boolean When true, include test execution history (name, status, execution time) for each run; when false, omit tests to keep the response smaller. Default: false
name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
num_runs: integer Number of historical runs to return (1–100). Default 1 returns the latest run only; use higher values to analyze performance trends. Default: 1
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_node_details Retrieves full details for a dbt resource by type and name or unique ID. Use this tool when you need the full schema, definition, or metadata for a specific dbt resource. The `resource_type` determines what fields are returned. **Parameters:** - `resource_type`: The type of dbt resource. One of: `model`, `source`, `exposure`, `test`, `seed`, `snapshot`, `macro`, `semantic_model`. The resource type is also encoded in the `unique_id` prefix (e.g. `model.my_project.orders` → `model`). - `name`: The resource's short name (e.g. `orders`). Provide `name` or `unique_id`, not both. - `unique_id`: The resource's fully qualified unique ID (e.g. `model.my_project.orders`). Preferred when available — avoids ambiguity when multiple resources share a name. **Usage examples:** ```python # Get details for a model by unique_id get_node_details(resource_type="model", unique_id="model.analytics.orders") # Get details for a source by name get_node_details(resource_type="source", name="raw_users") # Get details for a semantic model get_node_details(resource_type="semantic_model", unique_id="semantic_model.analytics.orders") ```

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
resource_type required: The type of dbt resource to fetch details for. One of: model, source, exposure, test, seed, snapshot, macro, semantic_model. Tip: the resource_type is encoded in the unique_id prefix (e.g. `model.my_project.orders` → model).
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_product_doc_pages Retrieve the Markdown content of one or more dbt documentation pages from docs.getdbt.com. Pass a list of URLs or relative paths (e.g. from search_product_docs results). Up to 5 pages can be fetched per call; pages are fetched in parallel for speed. Pass the optional `query` parameter to retrieve only the most relevant sections of each page rather than the full content — this significantly reduces response size and is recommended when you already know what topic you are looking for. IMPORTANT — how to present docs content to the user: 1. Give a direct answer first, then explain. Don't just summarize — be specific about WHERE to find a feature in the UI and HOW it works. 2. Structure around the user's task: lead with what they asked, not the doc's own structure. Include step-by-step actionable detail when the docs describe a workflow or UI feature. 3. Call out practical limitations and edge cases from the docs. 4. Close with clear guidance: if the feature only partially answers the question, say what else they can do and where. 5. ALWAYS include the docs page URL(s) as markdown hyperlinks at the end of your response, e.g. [Page title](https://docs.getdbt.com/...). VERSION AWARENESS: The response includes a `dbt_project_version` field with the user's installed dbt version (detected via `dbt --version`). Page content is automatically filtered to show only sections relevant to the detected version — VersionBlock tags from the docs site are resolved so you receive clean, version-appropriate markdown. Pages may also have a `version_note` field if they cover an EOL version. If `dbt_project_version` is null, the version could not be detected — all version-specific content is kept with tags stripped. When presenting page content to the user, you MUST: 1. If `dbt_project_version` is set, tell the user their detected version upfront (e.g. "You're on dbt 1.8"). 2. If `version_note` is set, prominently warn the user that the page is for an end-of-life version and the information may be outdated. Suggest they look at the current docs instead. 3. Page content has already been filtered to show only sections relevant to the detected version. If the content seems sparse or incomplete, let the user know that some sections may have been filtered out because they apply to a different dbt version, and suggest they check the full page on docs.getdbt.com.

Arguments

paths required: array List of docs.getdbt.com URLs or relative paths to fetch (e.g. ['/docs/build/incremental-models', '/docs/build/models']). Max 5 pages per call.
query: Optional search query. When provided, only the most relevant sections of each page are returned instead of the full content, significantly reducing response size. Default: null

get_seed_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_semantic_model_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_snapshot_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_source_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

get_test_details **DEPRECATED — use `get_node_details` instead.** This tool will be removed in a future release.

Arguments

name: The name of the resource. This is not required if `unique_id` is provided. Only use name when `unique_id` is unknown. Default: null
unique_id: Fully-qualified unique ID of the resource. This will follow the format `<resource_type>.<package_name>.<resource_name>` (e.g. `model.analytics.stg_orders`). Strongly preferred over the `name` parameter for deterministic lookups. Default: null

list_job_run_artifacts List all available artifacts for a completed dbt job run. This tool retrieves the list of artifact files generated during a run execution, such as manifest.json, catalog.json, and run_results.json. ## Returns List of artifact file paths available for download. Common artifacts include: - **manifest.json**: Complete project metadata and lineage - **catalog.json**: Documentation and column information - **run_results.json**: Execution results and timing - **sources.json**: Source freshness check results ## Excluded Artifacts The following artifact prefixes are excluded from results: - **compiled/**, **run/**: Per-node SQL files — too numerous to be useful and not human/LLM readable in bulk - **index/**, **metadata/**: dbt docs v2 / dbt Information Schema Parquet files — binary format, not yet supported ## Artifact Availability Artifacts are only available for: - Successfully completed runs - Failed runs that progressed beyond compilation - Runs where `artifacts_saved` is true ## Use Cases - Discover available artifacts before downloading - Check if specific artifacts were generated - Audit artifact generation across runs - Integrate with external systems that consume dbt artifacts - Validate run completion and output generation ## Example Usage ```json { "run_id": 789 } ``` ## Next Steps Use `get_job_run_artifacts` to download specific artifacts from this list for analysis or integration with other tools.

Arguments

run_id required: integer The dbt job run ID

list_jobs List a page of jobs in a dbt platform account with optional filtering. This tool retrieves jobs from the dbt Admin API. Jobs are the configuration for scheduled or triggered dbt runs. Pass `project_id` to list jobs across all environments in that project. This overrides the configured production environment filter. When `project_id` is omitted, results remain scoped to the configured production environment, or to the account if no environment is configured. Use `limit` and `offset` to page through large result sets. The `result` field contains a list of job objects with details like: - Job ID, name, and description - Environment ID and project ID the job belongs to - Schedule configuration - Execute steps (dbt commands) - Trigger settings Use this tool to explore available jobs, understand job configurations, or find specific jobs to trigger. Returns one page in `result`, with `pagination.has_more` and `pagination.next_offset`. Use the next offset with the same filters. `limit` defaults to 50 and is capped at 100.

Arguments

limit: integer Maximum items in this page (1–100, default 50). Default: 50
offset: integer Offset returned by the previous page's next_offset. Default: 0
project_id: List jobs across all environments in this project, overriding the configured production environment filter. When omitted, use the configured production environment, or list all account jobs if none is configured Default: null

list_jobs_runs List all job runs in a dbt platform account with optional filtering. This tool retrieves runs from the dbt Admin API. Runs represent executions of dbt jobs in dbt. The `result` field contains a list of run objects with details like: - Run ID and status - Job information - Start and end times - Git branch and SHA - Artifacts and logs information Use this tool to monitor job execution, check run history, or find specific runs for debugging. Returns one page in `result`, with `pagination.has_more` and `pagination.next_offset`. Use the next offset with the same filters. `limit` defaults to 50 and is capped at 100.

Arguments

job_id: When set, only include runs for this job definition ID Default: null
limit: integer Maximum items in this page (1–100, default 50). Default: 50
offset: integer Offset returned by the previous page's next_offset. Default: 0
order_by: Sort field (e.g. "created_at", "finished_at", "id"); prefix with "-" for descending order (e.g. "-created_at" for newest first) Default: null
status: Filter by run status: queued, starting, running, success, error, or cancelled Default: null

list_metrics List metrics from the dbt Semantic Layer. The `result` field is a CSV string with a header row. Columns are dynamic: a column is only present if at least one metric has a non-empty value for it. `name` and `type` are always present; `label`, `description`, `metadata`, `dimensions`, and `entities` are included only when at least one metric has a value. The `dimensions` and `entities` cells contain comma-separated lists of names. When the number of metrics is below the configured threshold (default: 10), each metric includes the names of its available dimensions and entities. Use get_dimensions or get_entities for full details (types, granularities, descriptions) on specific metrics. When above the threshold, only metrics are returned. `metric_time` is a standard time dimension available on most metrics — you can often query directly without calling `get_dimensions` first. Call `get_dimensions` only when you need non-time dimensions or specific granularity details. For listings that exceed the text budget, columns are dropped progressively to save tokens: `description` is dropped first; `metadata` is dropped only if removing `description` alone is not enough. The CSV is prefixed with one or more `# Note:` lines listing which columns were omitted. When that happens, call `list_metrics` again with the `search` parameter to retrieve those fields for the specific metrics you care about. `search` accepts either a single substring or a list of substrings; when a list is provided, metrics whose name matches **any** of the substrings are returned (deduplicated), so you can fetch details for several metrics in one call. `meta_filter` accepts a dict of key-value pairs and restricts results to metrics whose `config.meta` contains all specified pairs — for example `{"agent_accessible": true}`. Apply it on broad searches to keep the result set small enough that the `metadata` column is preserved in the response. If the user is asking a data-related or business-related question, use this tool as a first step. Returns one source page in `result`, with `pagination.has_more` and `pagination.next_page`. Pass the next page as `page_num` with the same filters and `page_size` (default 50, maximum 100). Local filtering may leave an empty page with more pages available. Restart at page 1 if you reduce the page size after a size-limit error.

Arguments

meta_filter: Filter metrics by their config.meta key-value pairs. Only metrics whose metadata contains all specified key-value pairs are returned. Example: {"agent_accessible": true} returns only metrics where config.meta.agent_accessible is true. Use JSON booleans (true/false), not strings — "true" and "false" strings are normalized to booleans automatically. Use this to narrow a broad listing before the size budget is evaluated, so that the metadata column is preserved in the response. Default: null
page_num: integer One-based page number; keep filters and page size unchanged. Default: 1
page_size: integer Maximum items in this page (1–100, default 50). Default: 50
search: Filter metrics by substring match against the metric name. Accepts either a single substring or a list of substrings; when a list is provided, metrics matching any of the substrings are returned (deduplicated). Default: null

list_projects List all active projects in the dbt Cloud account. This tool retrieves projects from the dbt Admin API. Projects are the top-level organizational unit in dbt Cloud, each associated with a git repository containing dbt code. The `result` field contains a list of project objects with: - **id**: The project ID - **name**: The project name - **description**: The project description (if set) - **dbt_project_subdirectory**: Path within the repository where the dbt project lives (if set) - **has_semantic_layer**: Whether the project has a semantic layer configured - **type**: The project type (0=default, 1=hybrid) - **environments**: List of environments, each with id, name, and type (development, production, staging, or generic) - **repository_full_name**: The repository name in `org/repo` format (if set) Use this tool to discover available projects in the account, especially when working across multiple projects. Returns one page in `result`, with `pagination.has_more` and `pagination.next_offset`. Use the next offset with the same filters. `limit` defaults to 50 and is capped at 100.

Arguments

limit: integer Maximum items in this page (1–100, default 50). Default: 50
offset: integer Offset returned by the previous page's next_offset. Default: 0

list_saved_queries List all saved queries from the dbt Semantic Layer. Saved queries are pre-defined queries that have been saved in the Semantic Layer. They contain specific metrics, group-by dimensions, and filters that are commonly used. This tool helps discover what predefined queries are available for quick execution. Use this tool when: - The user wants to see what pre-built queries are available - The user mentions "saved queries" or "predefined queries" - You need to find commonly used analytical queries Examples: - "What saved queries are available?" - "Show me the predefined reports" - "List all saved queries for revenue analysis" Returns one source page in `result`, with `pagination.has_more` and `pagination.next_page`. Pass the next page as `page_num` with the same filters and `page_size` (default 50, maximum 100). Local filtering may leave an empty page with more pages available. Restart at page 1 if you reduce the page size after a size-limit error.

Arguments

page_num: integer One-based page number; keep filters and page size unchanged. Default: 1
page_size: integer Maximum items in this page (1–100, default 50). Default: 50
search: Filter saved queries by substring match on name, label, or description Default: null

query_metrics <instructions> Queries the dbt Semantic Layer to answer business questions from the data warehouse. This tool allows ordering and grouping by dimensions and entities. To use this tool, you must first know about specific metrics, dimensions and entities to provide. You can call the list_metrics, get_dimensions, and get_entities tools to get information about which metrics, dimensions, and entities to use. When using the `order_by` parameter, each item must refer to either a metric name or a field that also appears in `group_by`. For time dimensions, you may specify a `grain` in `order_by` independently from `group_by`; if omitted, it defaults to the grain of the matching `group_by` entry. `grain` only applies to time dimensions and should be omitted for metrics and categorical dimensions. When fulfilling a lookback query, prefer using order_by and limit instead of using the where parameter. A lookback query requires that the `order_by` parameter includes a descending order for a time dimension. The `where` parameter should be database agnostic SQL syntax, however dimensions and entity are referenced differently. For categorical dimensions, use `{{ Dimension('<name>') }}` and for time dimensions add the grain like `{{ TimeDimension('<name>', '<grain>') }}`. For entities, use `{{ Entity('<name>') }}`. When referencing dates in the `where` parameter, only use the format `yyyy-mm-dd`. Pass the `where` value as a plain string — do not wrap it in additional quotes. Don't call this tool if the user's question cannot be answered with the provided metrics, dimensions, and entities. Instead, clarify what metrics, dimensions, and entities are available and suggest a new question that can be answered and is approximately the same as the user's question. For queries that may return large amounts of data, it's recommended to use a two-step approach: 1. First make a query with a small limit to verify the results are what you expect 2. Then make a follow-up query without a limit (or with a larger limit) to get the full dataset IMPORTANT: Do the below if the GET_MODEL_HEALTH tool is enabled. When responding to user requests to pull metrics data, check the health of the dbt models that are the parents of the dbt semantic models. Use the instructions from the "ASSESSING MODEL HEALTH" section of the get_model_health() prompts to do this. </instructions> <examples> <example> Question: "What were our total sales last month?" Thinking step-by-step: - I know "total_sales" is the metric I need - I know "metric_time" is a valid dimension for this metric and supports MONTH grain - I need to group by metric_time to get monthly data - Since this is time-based data, I should order by metric_time. I am also grouping by metric_time, so this is valid. - The user is asking for a lookback query, so I should set descending to true so the most recent month is at the top of the results. - The user is asking for just the last month, so I should limit to 1 month of data Parameters: metrics=["total_sales"] group_by=[{"name": "metric_time", "grain": "MONTH", "type": "time_dimension"}] order_by=[{"name": "metric_time", "grain": "MONTH", "descending": true}] limit=1 </example> <example> Question: "Show me our top customers by revenue in the last quarter" Thinking step-by-step: - First, I need to find the revenue metric - Using list_metrics(), I find "revenue" is available - I need to check what dimensions are available for revenue - Using get_dimensions(["revenue"]), I see "customer_name" and "metric_time" supports QUARTER grain - I need to check what entities are available - Using get_entities(["revenue"]), I confirm "customer" is an entity - I need quarterly time grain - Since this is time-based data, I should order by metric_time. I am grouping by metric_time, so this is valid. This is a lookback query, so I should set descending to true. - I should also order by revenue to see top customers. I am grouping by revenue, so this is valid. The user is asking for the highest revenue customers, so I should set descending to true. - I should limit to top 5 results to verify the query works Parameters: metrics=["revenue"] group_by=[{"name": "customer_name", "type": "dimension"}, {"name": "metric_time", "grain": "QUARTER", "type": "time_dimension"}] order_by=[{"name": "metric_time", "grain": "QUARTER", "descending": true}, {"name": "revenue", "descending": true}] limit=5 Follow-up Query (after verifying results): metrics=["revenue"] group_by=[{"name": "customer_name", "type": "dimension"}, {"name": "metric_time", "grain": "QUARTER", "type": "time_dimension"}] order_by=[{"name": "metric_time", "grain": "QUARTER", "descending": true}, {"name": "revenue", "descending": true}] limit=null </example> <example> Question: "What's our average order value by product category for orders over $100?" Thinking step-by-step: - I know "average_order_value" is the metric I need - I know "product_category" is a valid dimension - I need to filter for orders over $100 - No time dimension needed - I should first limit results to verify the query works Parameters (initial query): metrics=["average_order_value"] group_by=[{"name": "product_category", "type": "dimension"}] where="{{ Dimension('order_value') }} > 100" limit=10 Follow-up Query (after verifying results): metrics=["average_order_value"] group_by=[{"name": "product_category", "type": "dimension"}] where="{{ Dimension('order_value') }} > 100" limit=null </example> <example> Question: "How many new users did we get each week last year?" Thinking step-by-step: - First, I need to find the new users metric - Using list_metrics(), I find "new_users" is available - I need to check what dimensions are available - Using get_dimensions(["new_users"]), I see "metric_time" supports WEEK grain - I need to check what entities are available - Using get_entities(["new_users"]), I confirm "user" is an entity - I need weekly time grain - I need to group by metric_time - Since this is time-based data, I should order by metric_time to show progression - I need to filter for the previous year's data using proper time dimension syntax - Should first get a few weeks to verify the query works Parameters (initial query): metrics=["new_users"] group_by=[{"name": "metric_time", "grain": "WEEK", "type": "time_dimension"}] order_by=[{"name": "metric_time", "grain": "WEEK", "descending": false}] where="{{ TimeDimension('metric_time', 'WEEK') }} >= '2023-01-01' AND {{ TimeDimension('metric_time', 'WEEK') }} < '2024-01-01'" limit=4 Follow-up Query (after verifying results): metrics=["new_users"] group_by=[{"name": "metric_time", "grain": "WEEK", "type": "time_dimension"}] order_by=[{"name": "metric_time", "grain": "WEEK", "descending": false}] where="{{ TimeDimension('metric_time', 'WEEK') }} >= '2023-01-01' AND {{ TimeDimension('metric_time', 'WEEK') }} < '2024-01-01'" limit=null </example> <example> Question: "What's our customer satisfaction score by region?" Thinking step-by-step: - First, I need to check if we have a customer satisfaction metric - Using list_metrics(), I find we don't have a direct "customer_satisfaction" metric - I should check what metrics we do have that might be related - I see we have "net_promoter_score" and "customer_retention_rate" - I should inform the user that we don't have a direct customer satisfaction metric - I can suggest using NPS as a proxy for customer satisfaction Response to user: "I don't have a direct customer satisfaction metric, but I can show you Net Promoter Score (NPS) by region, which is often used as a proxy for customer satisfaction. Would you like to see that instead?" If user agrees, then: Parameters: metrics=["net_promoter_score"] group_by=[{"name": "region", "type": "dimension"}] order_by=[{"name": "net_promoter_score", "descending": true}] limit=10 </example> </examples>

Arguments

group_by: Group by dimensions, time dimensions, or entities; each item has `name`, `type` (`"dimension"`, `"time_dimension"`, or `"entity"`), and optional `grain` for time dimensions Default: null
limit: Maximum number of results to return Default: null
metrics required: array Metric names from list_metrics to query or inspect
order_by: Sort keys; each item has `name`, `descending` (default false), and optional `grain` for time dimensions (overrides the grain from group_by; falls back to the matching group_by grain when omitted); items may be metric names or group_by fields Default: null
where: Semantic Layer filter; use {{ Dimension('name') }}, {{ TimeDimension('name', 'grain') }}, {{ Entity('name') }}; dates as yyyy-mm-dd Default: null

retry_job_run Retry a failed dbt job run from the point of failure. This tool allows you to restart a failed run, continuing from where it failed rather than starting completely over. ## Returns New run object for the retry attempt with a new run ID and execution details. ## Requirements for Retry - Original run must have failed (status 20) - Run must be the most recent run for the job - dbt version must support retry functionality - Run must have generated run_results.json ## Retry Behavior - Continues from the failed step - Skips successfully completed models - Uses the same configuration as the original run - Creates a new run with a new run ID - Maintains the same Git SHA and branch ## Use Cases - Recover from transient infrastructure failures - Continue after warehouse connectivity issues - Resume after temporary resource constraints - Avoid re-running expensive successful steps - Quick recovery from known, fixable issues ## Retry Not Supported Reasons If retry fails, possible reasons include: - **RETRY_UNSUPPORTED_CMD**: Command type doesn't support retry - **RETRY_UNSUPPORTED_VERSION**: dbt version too old - **RETRY_NOT_LATEST_RUN**: Not the most recent run for the job - **RETRY_NOT_FAILED_RUN**: Run didn't fail - **RETRY_NO_RUN_RESULTS**: Missing run results for retry logic ## Example Usage ```json { "run_id": 789 } ``` This creates a new run that continues from the failure point of run 789.

Arguments

run_id required: integer The dbt job run ID

search_product_docs Search the dbt product documentation at docs.getdbt.com for pages matching a query. Returns matching page titles, URLs, and descriptions ranked by relevance. Only returns metadata, not page content — use get_product_doc_pages with URLs from the results to retrieve full page content. If the title/description search finds few matches, it automatically falls back to a deep full-text search across all documentation content to find pages where the topic is discussed in the body text. If your first query returns few results, try rephrasing with synonyms or the full term (e.g. 'user-defined functions' instead of 'UDFs', 'version control' instead of 'git'). Use the abbreviations on the page as well. VERSION AWARENESS: The response includes a `dbt_project_version` field (e.g. "1.8") detected by running `dbt --version` against the user's installed dbt binary. If null, the version could not be detected — present docs normally without version-specific callouts. When presenting results to the user, you MUST: 1. State the user's detected dbt version upfront if available (e.g. "Based on your project (dbt 1.8), here's what I found:"). 2. If a result title or description clearly references an older/EOL version (v1.6 or earlier), flag it: "Note: this page covers dbt v1.X, which has reached end-of-life and is no longer supported." 3. Search results only include titles, descriptions, and URLs — not page content. Do NOT make version-specific claims based on search results alone. If the user needs to know whether a feature applies to their version, fetch the page with `get_product_doc_pages` first.

Arguments

query required: string

trigger_job_run # Trigger Job Run Trigger a dbt job run with optional parameter overrides. This tool starts a new run for a specified job with the ability to override default settings like Git branch, schema, or other execution parameters. ## Returns Run object with information about the newly triggered run including: - Run ID and status - Job and environment information - Git branch and SHA being used - Trigger information and cause - Execution queue position ## Use Cases - Trigger ad-hoc job runs for testing - Run jobs with different Git branches for feature testing - Execute jobs with schema overrides for development - Trigger jobs via API automation or external systems - Run jobs with custom parameters for specific scenarios - Verify a project builds on a newer dbt version before switching the environment over to it ## Example Usage ```json { "job_id": 456, "cause": "Manual trigger for testing" } ``` ```json { "job_id": 456, "cause": "Testing feature branch", "git_branch": "feature/new-models", "schema_override": "dev_testing" } ``` ```json { "job_id": 456, "cause": "Selective production build", "steps_override": ["dbt run --select my_model+ --full-refresh"] } ```

Arguments

cause: string Why this run is being triggered (recorded in run history on the dbt platform) Default: Triggered by dbt MCP
dbt_version_override: Override the dbt version this run executes on, without changing the job or its environment. Accepts a release track (e.g. "latest", "compatible", "extended") or a pinned version (e.g. "1.9.0") Default: null
git_branch: Override the Git branch to check out for this run Default: null
git_sha: Override the Git commit SHA to check out for this run Default: null
job_id required: integer The dbt job definition ID
schema_override: Override the destination schema for this run Default: null
steps_override: Replace the job's default dbt commands; each entry is a full dbt command (e.g. "dbt run --select my_model+ --full-refresh") Default: null

Resources

get-lineage

ui://dbt-mcp/get-lineage

What it does

Available functions

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Arguments

Resources

Questions people ask

Give the agent the transformation graph.