dbt MCP Server (Official)

What is dbt MCP Server (Official)?

The dbt MCP server is the official Model Context Protocol server from dbt Labs that gives AI agents context and tools for your dbt project across dbt Core, dbt Fusion and the dbt platform: lineage, model metadata, Semantic Layer metrics, dbt CLI commands and job management.

It comes in two forms. The self-hosted server runs on your machine with uvx dbt-mcp and suits development work such as authoring models, tests and docs. The remote server is hosted by dbt at https://YOUR_DBT_HOST_URL/api/ai/v1/mcp and suits consumption work such as querying metrics, exploring metadata and viewing lineage, with no install.

How to use dbt MCP Server (Official)?

Self-hosted prerequisites: install uv, and have a local dbt project if you want CLI tools. You don't need to clone the dbt-mcp repository. For dbt platform features, you need your access URL (for example abc123.us1.dbt.com) and either OAuth or a token.

Key environment variables: DBT_PROJECT_DIR (folder containing dbt_project.yml) and DBT_PATH (full path to your dbt executable; find it with which dbt) for CLI use; DBT_HOST, DBT_TOKEN, DBT_PROD_ENV_ID and, for the Admin API or PAT auth, DBT_ACCOUNT_ID for the platform.

Claude Desktop

The quickest route is the dbt-mcp.mcpb bundle: download it from the latest GitHub release, double-click it to open in Claude Desktop, enter your dbt platform host and enable the server. For a manual setup, open Settings > Developer > Edit Config and add:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable",
        "DBT_HOST": "YOUR-ACCESS-URL"
      }
    }
  }
}

Omit DBT_HOST for CLI-only use, or omit the two CLI variables for platform-only use. To use the remote server, add a custom connector under Chat > Customize > Connectors with your MCP URL and complete the OAuth flow.

Claude Code

Connect to the remote server:

claude mcp add --transport http dbt https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/

For token-based auth, use a project .mcp.json with headers:

{
  "mcpServers": {
    "dbt": {
      "type": "http",
      "url": "https://YOUR_DBT_HOST_URL/api/ai/v1/mcp/",
      "headers": {
        "Authorization": "Token YOUR_DBT_ACCESS_TOKEN",
        "x-dbt-prod-environment-id": "DBT_PROD_ENV_ID"
      }
    }
  }
}

Cursor and VS Code

dbt publishes integration guides for both. The self-hosted uvx dbt-mcp block above works as the mcpServers entry in Cursor's mcp.json; in VS Code, the same command and env go under servers in .vscode/mcp.json.

Key features of dbt MCP Server (Official)

• Official, open-source server from dbt Labs (Apache-2.0)
• Works with dbt Core, dbt Fusion and the dbt platform
• Self-hosted via uvx dbt-mcp, or remote over HTTP with OAuth or token headers
• Lineage and model health from the Discovery API, including column-level lineage
• Semantic Layer queries for metrics, dimensions and saved queries
• dbt CLI commands such as build, run, test and compile (self-hosted only)
• Admin API tools to list, trigger, cancel and retry job runs
• Fine-grained control with DISABLE_* variables or x-dbt-disable-tools headers

dbt MCP Server (Official) tools

Tools are grouped into toolsets that you can turn on or off:

• Discovery: get_all_models, get_lineage, get_node_details, get_model_health and get_all_sources explore project metadata. Several older detail tools are deprecated in favor of get_node_details.
• Semantic Layer: list_metrics, get_dimensions, query_metrics and get_metrics_compiled_sql.
• SQL: execute_sql and text_to_sql. These are disabled by default on self-hosted; execute_sql needs a personal access token, and text_to_sql is the only tool that consumes dbt Copilot actions.
• dbt CLI: build, compile, run, test, show, parse, list and docs. These can modify your models and warehouse objects.
• Admin API: list_jobs, trigger_job_run, get_job_run_error, retry_job_run and cancel_job_run.
• Codegen: generate_source, generate_model_yaml and generate_staging_model (off by default; requires the dbt-codegen package).
• dbt LSP and docs: get_column_lineage, fusion.compile_sql, and search_product_docs for docs.getdbt.com.

Use cases of dbt MCP Server (Official)

• Impact analysis: "What models are downstream of stg_orders, and which dashboards depend on them?"
• Metric questions: "What is the total revenue for the last 30 days?" answered through the Semantic Layer.
• Debugging jobs: "Why did last night's production job fail? Show the error and retry it."
• Development: "Generate a staging model and YAML for the raw.payments source, then run its tests."
• Model health checks: "Which mart models have failing tests or stale sources?"
• Docs lookups: "Search the dbt docs for how incremental models handle schema changes."

dbt MCP Server (Official) vs alternatives

The main choice is between the two official variants. The self-hosted dbt MCP server gives you CLI commands, codegen and local manifest tools for development. The remote server needs no install and covers Semantic Layer, SQL, Discovery and docs tools, but does not run dbt CLI commands. If you only need to query the warehouse directly without dbt context, a database server such as Postgres MCP is simpler but has no knowledge of models, lineage or metrics.

Troubleshooting dbt MCP Server (Official)

• spawn uvx ENOENT or "Could not connect to MCP server": the client can't find uvx. Run which uvx (macOS/Linux) or where uvx (Windows) and use the full path as command.
• OAuth login doesn't start: a leftover lock file may block it. Close the client, run rm -f ~/.dbt/mcp.yml ~/.dbt/mcp.lock, and restart. Also confirm an account admin enabled dbt Wizard features.
• execute_sql fails with a service token: it requires a personal access token, or OAuth on the remote server.
• IDs rejected: use numeric values, for example DBT_PROD_ENV_ID=54321, not dashboard URLs.
• SQL or codegen tools are missing: they are disabled by default. Set DISABLE_SQL=false or DISABLE_DBT_CODEGEN=false.