configuring-dbt-mcp-server_skill

This skill guides you through configuring and troubleshooting the dbt MCP server for Claude, Cursor, and VS Code to enable seamless AI tooling.

Python

152

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill dbt-labs/dbt-agent-skills --skill configuring-dbt-mcp-server

SKILL.md14.2 KB

Overview

This skill helps you set up, configure, and troubleshoot a dbt MCP server to connect AI clients (Claude, Cursor, VS Code) to dbt CLI, Semantic Layer, Discovery API, and Admin API. It guides you through choosing local vs remote servers, preparing credentials, and applying client-specific configuration templates. The goal is a working MCP connection so AI tools can list models, query metrics, and run CLI tasks where permitted.

How this skill works

It inspects your desired server type (local uvx-hosted or remote HTTP endpoint), required environment variables, and client integration requirements, then produces the correct JSON or command-line configuration. It validates prerequisites (uv installation, dbt project and binary paths, tokens/IDs) and provides verification and troubleshooting steps to confirm the MCP server is reachable and tools are accessible.

When to use it

You need AI access to local dbt CLI (run, build, test) for development or debugging.
You want AI tools to query metrics or explore metadata without local dbt (consumption only).
You are onboarding a team and need a reproducible project-specific MCP config (.mcp.json).
You must enable or restrict specific tools (Semantic Layer, Discovery, Admin API) via env vars.
You need to configure OAuth or token auth for dbt Cloud integration.

Best practices

Choose local server (uvx dbt-mcp) for development and CLI access; use remote for read-only consumption.
Store sensitive tokens in a .env file and reference it from the uvx config rather than hard-coding in JSON.
Use project-scoped .mcp.json or workspace settings for team-shared configs; use user scope for personal setups.
Use Personal Access Tokens (PAT) for execute_sql and developer-level interactions; use service tokens for CI/automation.
Verify DBT_PROJECT_DIR and DBT_PATH before launching uvx to avoid spawn/ENOENT errors.

Example use cases

Local development: run uvx --env-file .env dbt-mcp to enable Claude Desktop to run dbt build and list models.
Remote consumption: configure a remote MCP url with Authorization header so VS Code chat can query metrics.
Team onboarding: commit a project .mcp.json pointing to a shared .env and document required env vars.
Troubleshooting: replace 'uvx' with its absolute path in the command when encountering 'uvx not found'.
CI automation: use a service token with minimal permissions for Discovery API calls (no execute_sql).

FAQ

Use a Personal Access Token (PAT). Service tokens cannot be used for execute_sql.

Why does VS Code use a different key name?

VS Code expects the config under 'servers' rather than 'mcpServers', so adapt the JSON accordingly.

How do I test a local MCP server quickly?

Create a minimal .env with DBT_PROJECT_DIR and DBT_PATH, then run uvx --env-file .env dbt-mcp and look for no startup errors.