skilld
All skills
dbt-labs avatar

/configuring-dbt-mcp-server

@faadc25 official
by dbt Labsdbt-labs/dbt-agent-skills729 stars
62

Generates MCP server configuration JSON, resolves authentication setup, and validates server connectivity for dbt. Use when setting up, configuring, or troubleshooting the dbt MCP server for AI tools like Claude Desktop, Claude Code, Cursor, or VS Code.

Ask your Agent

Use this Skill: https://skilld.dev/gh/dbt-labs/dbt-agent-skills/configuring-dbt-mcp-server

This session only. Nothing lands on disk.

referencestroubleshooting.md

≈359 tokens on demand. Your agent reads this file only when SKILL.md points to it.

Troubleshooting

"uvx not found" or "spawn uvx ENOENT"

Find full path and use it in config:

# macOS/Linux
which uvx
# Use output like: /opt/homebrew/bin/uvx

# Windows
where uvx

Update config:

{
  "command": "/opt/homebrew/bin/uvx",
  "args": ["dbt-mcp"]
}

"Could not connect to MCP server"

  1. Check uvx is installed: uvx --version
  2. Verify paths exist: ls $DBT_PROJECT_DIR/dbt_project.yml
  3. Check dbt works: $DBT_PATH --version

OAuth Not Working

Only accounts with static subdomains (e.g., abc123.us1.dbt.com) support OAuth. Check your Access URLs in dbt platform settings.

Remote Server Returns 401/403

  • Verify token has Semantic Layer and Developer permissions
  • For execute_sql: Use personal access token, not service token
  • Check environment ID is correct (from Orchestration page)

Common Mistakes

Mistake Fix
Using npm/npx instead of uvx The package is dbt-mcp via uvx, not npm
Wrong env var names (DBT_CLOUD_*) Use DBT_TOKEN, DBT_PROD_ENV_ID, etc.
Using mcpServers in VS Code VS Code uses servers key in mcp.json
Service token for execute_sql Use personal access token for SQL tools
Windows paths in WSL Use Linux paths (/home/...) not Windows
Local user settings in WSL Must use Remote settings in VS Code
Missing uv installation Install uv first: https://docs.astral.sh/uv/

Source: SKILL.md on GitHub

Third-party checks

1 warning17d5 checks · Risk SAFE
  • Gen Agent Trust Hub17d

    The skill provides instructions and configuration templates for setting up the dbt Model Context Protocol (MCP) server. It emphasizes security best practices for credential management and uses standard tools from dbt-labs.

  • Socket17d

    No alerts

  • Snyk17d

    Risk: LOW · No issues

  • Runlayer6mo

    3/4 files flagged

  • ZeroLeaks5mo

    Score: 93/100 · 2 sections analyzed

Provenance

Signed by skilld at faadc25. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 2 days ago.

Activeupdated 7 months ago

Capability

user-invocable
false
metadata
{
  "author": "dbt-labs"
}

Topics

  • MCP
  • API
  • dbt
  • configuration
  • claude
  • cursor
  • vscode
  • authentication
  • semantic-layer

README badge

README badge for dbt-labs/dbt-agent-skills/configuring-dbt-mcp-server

What it does

Generates MCP server configuration JSON for dbt, handles credential setup, and validates connectivity across local and remote server types for Claude Desktop, Claude Code, Cursor, and VS Code. Use this when installing or troubleshooting the dbt MCP server to enable AI agents to access the dbt CLI, Semantic Layer, Discovery API, and Admin API.

Generated from the current SKILL.md.

Frequently asked

Does this skill work with Claude Desktop, Cursor, and VS Code?
Yes. The skill provides client-specific setup instructions for Claude Desktop, Claude Code, Cursor, and VS Code, with different configuration paths and formats for each.
What is the difference between local and remote dbt MCP server?
Local server runs via `uvx` on your machine and supports CLI commands (run, build, test) plus platform features if you add credentials. Remote server connects via HTTP to dbt Cloud and handles consumption only (querying metrics, exploring metadata) without CLI access.
Do I need a dbt Cloud account to use this skill?
Not for local CLI-only setups. A dbt Cloud account is required only if you want platform features (Semantic Layer, Discovery API, Admin API) or if you use the remote server.
How should I store sensitive credentials like tokens?
Use environment variable references (e.g., `${DBT_TOKEN}`) in config files instead of literal values, store tokens in `.env` files added to `.gitignore`, and never commit or log token values.
Can I enable SQL and codegen tools?
Yes, but they are disabled by default. Set `DISABLE_SQL=false` or `DISABLE_DBT_CODEGEN=false` as environment variables to enable them.

Generated from the current SKILL.md. These answers refresh after source changes.