dbt MCP Server

What does a dbt MCP server do?

A dbt MCP server gives an AI assistant governed access to models, metrics, lineage and freshness. It can browse models and sources, query Semantic Layer metrics, and read job runs and errors. The self-hosted server also runs dbt commands such as dbt run, dbt build and dbt test on your project.

• Needs the dbt platform: Semantic Layer, Discovery, Admin API and execute_sql tools.
• Works without it: dbt CLI, Codegen and LSP tools, which work on a local project.
• Product Docs tools search docs.getdbt.com, so they say nothing about your project.
• Semantic Layer tools need metrics defined in dbt first. dbt implementation covers that work.

Is there an official dbt MCP server?

Yes. dbt Labs publishes both forms. The self-hosted server is the Apache-2.0 dbt-labs/dbt-mcp repo, and the remote server runs the same project on the dbt platform. Claude's directory also lists a dbt connector from dbt Labs, marked Anthropic verified and added in June 2026.

• Remote: for consumption such as metrics, metadata and lineage. dbt Labs says it's on all dbt platform plans, but your tools depend on the APIs your plan includes.
• Self-hosted: for development work such as authoring models, tests and documentation. It supports dbt v1, dbt v2 and the dbt platform CLI.

What is the dbt MCP server URL, and how do you sign in?

The remote URL differs per account, so copy it from Account settings > Access URLs > MCP Endpoint URL. It follows https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/. Sign in with OAuth, in public beta on Starter, Enterprise and Enterprise+, or a token in the Authorization header. The self-hosted server has no URL and runs from uvx dbt-mcp.

• OAuth needs a static subdomain, such as abc123 in abc123.us1.dbt.com. Without one, contact dbt support.
• Token setups also need the x-dbt-prod-environment-id header. execute_sql over a token needs a personal access token, x-dbt-dev-environment-id and x-dbt-user-id, and service tokens don't work for it.
• The self-hosted server reads DBT_HOST and DBT_TOKEN for platform tools, and DBT_PROJECT_DIR and DBT_PATH for dbt commands. It turns off any toolset that's missing a required variable.

What can a dbt MCP server read and change?

Reads cover models, lineage, metrics, job history and dbt's docs. What can change depends on the form. Remote can trigger, retry and cancel jobs and run execute_sql, which doesn't block write statements. Self-hosted adds dbt commands, and dbt Labs warns they can modify models, sources and warehouse objects.

• dbt Labs hasn't published a single read-only mode, so use these controls.
• Remote with OAuth: approve or deny each scope on the consent screen and pick selected projects. Leave jobs:run and projects:develop unticked for a read-focused connection.
• Remote with a token: x-dbt-disable-tools and x-dbt-disable-toolsets switch off tools for that client.
• Self-hosted: set DISABLE_DBT_CLI=true and DISABLE_ADMIN_API=true, or list only the toolsets you want with DBT_MCP_ENABLE_*. SQL tools are off by default here.
• execute_sql: it runs with your personal development credentials, so give those a least-privilege warehouse role.

What it can read

• Discovery: get_all_models, get_all_sources, get_lineage, get_model_health and get_model_performance.
• Semantic Layer: list_metrics, get_dimensions, get_metrics_compiled_sql and query_metrics.
• Job history: list_jobs, list_jobs_runs, get_job_run_details and get_job_run_error.
• Self-hosted project reads: list, parse, compile and get_lineage_dev.

What it can change

• Jobs: trigger_job_run, retry_job_run and cancel_job_run. trigger_job_run can override the git branch or schema.
• SQL: execute_sql has no block on write statements. Your warehouse role decides what it can do.
• Self-hosted dbt commands: run and build materialize models, and clone clones nodes into the target schema.

How do you set up a dbt MCP server in Claude, ChatGPT and Cursor?

For remote, copy your MCP Endpoint URL, add it to your client and approve scopes. dbt Labs documents Claude and Cursor in full, and names ChatGPT in one line. For self-hosted, install uv and add uvx dbt-mcp to your client's config with your project path.

{
  "mcpServers": {
    "dbt": {
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/"
    }
  }
}

What can you ask a dbt MCP server?

Start with lineage and job health, which read metadata and run nothing in your warehouse. Metric prompts run a query and count toward your plan. These examples fit the tools dbt Labs lists, so swap in your own names. The text_to_sql prompt uses a Copilot action, and the retry prompt rebuilds models.

• Reads

  Which models feed fct_ad_spend? Show two levels of upstream lineage and flag any with failing tests or stale sources.

  Copy

• Reads

  Why did last night's production job fail? Show the failed run and the error.

  Copy

• Reads

  List the metrics in our Semantic Layer, then show revenue by channel for the last 30 days.

  Copy

• Spends credits

  Write SQL for weekly paid signups by channel using this project's models. Show me the SQL and don't run it.

  Copy

• Writes

  Retry the failed job run. Tell me the run ID and the job's commands first.

  Copy

What are the limits of a dbt MCP server?

The remote server can't run dbt commands or reach local projects. It shares dbt's default limit of 5,000 requests per minute per IP. Self-hosted uses the public API limits, including 500 Discovery requests per minute. Self-hosted dbt commands time out after 60 seconds unless you raise DBT_CLI_TIMEOUT, which matters on a long build.

• Past an Administrative or Discovery API limit, dbt returns 429 and enforces a five-minute cooldown.
• dbt Labs says remote tools can change without notice. For a fixed set, it suggests pinning a version of the self-hosted server.
• Read-only users need warehouse credentials to run query_metrics. An admin can set one shared analytics credential.
• OAuth sessions end after 7 days of inactivity. To revoke access, remove the connector in your client. dbt Labs says a revoke option in the dbt platform is coming.

How much does a dbt MCP server cost?

The dbt-mcp code is open source, and dbt Labs hasn't published a separate MCP price. The Developer plan is free but excludes API access. Starter is $100 per user a month, with 15,000 models built and 5,000 queried metrics. Enterprise pricing is custom. Your warehouse bills every query and model build.

• text_to_sql is the only tool that uses dbt Copilot actions. Plans include 100 a month on Starter, 5,000 on Enterprise and 10,000 on Enterprise+, per license.
• Each successful Semantic Layer request counts as at least one queried metric, and each metric it calculates or renders counts. Metadata requests don't.
• Job runs started through the dbt API count as models built. Models built in a development environment don't, though your warehouse still bills them.

What are the alternatives to a dbt MCP server?

The main alternatives are a warehouse server, which queries tables without your dbt definitions, or a BI server with its own metric layer. Looker MCP fits if your metrics live in LookML. dbt Labs also documents guides for Snowflake Cortex and Databricks, so agents there can use the dbt server.

• Snowflake MCP: Direct warehouse queries, without dbt's metric definitions.
• BigQuery MCP: Direct warehouse queries, without dbt's metric definitions.
• Databricks MCP: The warehouse route, if your dbt project runs on Databricks.
• Looker MCP: Governed metrics, if your definitions live in LookML.

Which skill goes with a dbt MCP server?

Use the free Agent write safety skill before you allow job tools or dbt commands, because they can rebuild models and change warehouse objects. Use the Marketing context kit to record your metric definitions and model names once, so the assistant starts every prompt from the same rules and has less to guess.

• Agent write safety: Sets approvals before an agent can run jobs or dbt commands.
• Marketing context kit: Holds your metric definitions and model names in one folder for every prompt.