Labsco
dbt-labs logo

configuring-dbt-mcp-server

★ 605

by dbt-labs · part of dbt-labs/dbt-agent-skills

Generates MCP server configuration JSON, resolves authentication setup, and validates server connectivity for dbt. Use when setting up, configuring, or…

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#git#maps#security
🧩 One of 7 skills in the dbt-labs/dbt-agent-skills package — works on its own, and pairs well with its siblings.

Generates MCP server configuration JSON, resolves authentication setup, and validates server connectivity for dbt. Use when setting up, configuring, or…

Inspect the full instructions your agent will receiveExpand

This is the exact playbook injected into your agent when the skill activates — shown here so you can audit it before installing. You don't need to read it to use the skill.

by dbt-labs

Generates MCP server configuration JSON, resolves authentication setup, and validates server connectivity for dbt. Use when setting up, configuring, or… npx skills add https://github.com/dbt-labs/dbt-agent-skills --skill configuring-dbt-mcp-server Download ZIPGitHub605

Configure dbt MCP Server

Overview

The dbt MCP server connects AI tools to dbt's CLI, Semantic Layer, Discovery API, and Admin API. This skill guides users through setup with the correct configuration for their use case.

Decision Flow

Copy & paste — that's it
flowchart TB
 start([User wants dbt MCP]) --> q1{Local or Remote?}
 q1 -->|dev workflows, CLI access needed| local[Local Server uvx dbt-mcp]
 q1 -->|consumption only, no local install| remote[Remote Server HTTP endpoint]
 local --> q2{Which client?}
 remote --> q2
 q2 --> claude_desktop[Claude Desktop]
 q2 --> claude_code[Claude Code]
 q2 --> cursor[Cursor]
 q2 --> vscode[VS Code]
 claude_desktop --> config[Generate config + test setup]
 claude_code --> config
 cursor --> config
 vscode --> config

Questions to Ask

1. Server Type

Ask: "Do you want to use the local or remote dbt MCP server?"

Local Server Remote Server Runs on your machine via uvx Connects via HTTP to dbt platform Required for development (authoring models, tests, docs) but can also connect to the dbt platform for consumption (querying metrics, exploring metadata) Best for consumption (querying metrics, exploring metadata) Supports dbt CLI commands (run, build, test, show) No CLI commands (run, build, test) Works without a dbt platform account but can also connect to the dbt platform for development (authoring models, tests, docs) Requires dbt platform account No credit consumption Consumes dbt Copilot credits

2. MCP Client

Ask: "Which MCP client are you using?"

  • Claude Desktop

  • Claude Code (CLI)

  • Cursor

  • VS Code

3. Use Case (Local Server Only)

Ask: "What's your use case?"

CLI Only Platform Only Platform + CLI dbt Core/Fusion users dbt Cloud without local project Full access to both No platform account needed OAuth or token auth Requires paths + credentials

4. Tools to Enable

Ask: "Which tools do you want enabled?" (show defaults)

Tool Category Default Environment Variable dbt CLI (run, build, test, compile) Enabled DISABLE_DBT_CLI=true to disable Semantic Layer (metrics, dimensions) Enabled DISABLE_SEMANTIC_LAYER=true to disable Discovery API (models, lineage) Enabled DISABLE_DISCOVERY=true to disable Admin API (jobs, runs) Enabled DISABLE_ADMIN_API=true to disable SQL (text_to_sql, execute_sql) Disabled DISABLE_SQL=false to enable Codegen (generate models/sources) Disabled DISABLE_DBT_CODEGEN=false to enable

Credential Security

  • Always use environment variable references (e.g., ${DBT_TOKEN}) instead of literal token values in configuration files that may be committed to version control

  • Never log, display, or echo token values in terminal output

  • When using .env files, ensure they are added to .gitignore to prevent accidental commits

  • Recommend users rotate tokens regularly and use the minimum required permission set

Verification Steps

Test Local Server Config

Recommended: Use .env file

  • Create a .env file in your project root directory and add minimum environment variables for the CLI tools:
Copy & paste — that's it
DBT_PROJECT_DIR=/path/to/project
DBT_PATH=/path/to/dbt
  • Test the server:
Copy & paste — that's it
uvx --env-file .env dbt-mcp

Alternative: Environment variables

Copy & paste — that's it
# Temporary test (variables only last for this session)
export DBT_PROJECT_DIR=/path/to/project
export DBT_PATH=/path/to/dbt
uvx dbt-mcp

No errors = successful configuration.

Verify in Client

After setup, ask the AI:

  • "What dbt tools do you have access to?"

  • "List my dbt metrics" (if Semantic Layer enabled)

  • "Show my dbt models" (if Discovery enabled)

See Troubleshooting for common issues and fixes.

See Environment Variable Reference for the full list of supported variables.