Connect Claude Code to your dbt project

You have a dbt project (Core or Cloud) and you are tired of grepping the manifest to answer lineage questions. You want Claude to read your project as a structured graph, not as a folder of files. You want to be able to ask “what depends on stg_payments” in plain English and get the right answer.

You do not need to be a dbt power user. You do need to know your way around a terminal, have admin access (or friendly admin) to your dbt setup, and have Claude Code, Claude Desktop, or Cursor installed.

If you are reading the article version of this guide and clicked through for the setup, you are in the right place. If you landed here directly, the article that frames why any of this matters is here.

You need a few things in place before the install actually works. Skim the list. If anything is missing, fix that first.

• A dbt project that parses cleanly. Run dbt parse in your project directory. If it errors out, fix the errors before going any further. The MCP reads from target/manifest.json and a missing or stale manifest is the most common reason setup appears to fail.
• For Local mode: uv installed (the Python toolchain that ships uvx). uvx --help should respond. On macOS, brew install uv. On Linux, the curl install script in the docs. On Windows, follow the PowerShell installer carefully and reopen your terminal after.
• For Remote mode: a dbt Platform account with the Remote MCP feature enabled. Check Account Settings → AI in the dbt Platform UI. If Remote MCP is not listed, contact dbt support to enable it on your account.
• Claude Code, Claude Desktop, or Cursor installed. The MCP works the same in all three. The configs differ slightly, which is why this guide has each one separately.
• Read access to your dbt project repo if you are running Local against a cloned project, or to your dbt Platform environment if you are using Platform-backed features (Discovery API, Semantic Layer, Admin API).

The dbt MCP comes in two flavors. The choice is the most important decision in this guide. Pick the wrong one and you will spend an afternoon trying to get a feature working that does not exist on that path.

The Local server runs through uvx, which fetches the dbt-mcp package on demand. No virtualenv to manage, no pip install to debug. The whole thing is one config block in your MCP client and a handful of environment variables.

Step 1: Get your dbt Platform credentials

You need four values from dbt Platform. None of them are hard to find, but they live in different places.

• DBT_HOST: typically cloud.getdbt.com for US multi-tenant accounts, or your single-tenant URL.
• DBT_TOKEN: a Platform service token. Account Settings → Service Tokens → Create. Give it Developer access at minimum. Copy the token immediately; it is not shown again.
• DBT_PROD_ENV_ID: the numeric ID of your production deploy environment. Open the environment in dbt Platform; the ID is in the URL after /environments/.
• DBT_USER_ID: your user ID. Open your profile page in dbt Platform; the ID is in the URL after /users/.

If you are only using Local against a dbt Core project (no Platform features), you can skip these and just set DBT_PROJECT_DIR.

Step 2: Add the MCP server to your client

Pick the config block that matches your client. Paste it into the right config file. Reload the client.

The JSON shape is identical for all three clients. Only the config file path differs. Pick your client:

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/absolute/path/to/your/dbt/project",
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "dbtu_...",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_USER_ID": "67890"
      }
    }
  }
}

claude mcp add dbt -s user \
  --env DBT_PROJECT_DIR=/absolute/path/to/your/dbt/project \
  --env DBT_HOST=cloud.getdbt.com \
  --env DBT_TOKEN=dbtu_... \
  --env DBT_PROD_ENV_ID=12345 \
  --env DBT_USER_ID=67890 \
  -- uvx dbt-mcp

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/absolute/path/to/your/dbt/project",
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "dbtu_...",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_USER_ID": "67890"
      }
    }
  }
}

{
  "mcpServers": {
    "dbt": {
      "command": "uvx",
      "args": ["dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/absolute/path/to/your/dbt/project",
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_TOKEN": "dbtu_...",
        "DBT_PROD_ENV_ID": "12345",
        "DBT_USER_ID": "67890"
      }
    }
  }
}

If you went with Remote, the setup is shorter than reading this section.

1. In dbt Platform, open Account Settings → AI. Find the Remote MCP endpoint URL. It looks like https://your-account.dbt.com/api/mcp/v1/sse.
2. In Claude Code, run claude mcp add --transport sse dbt-remote https://your-account.dbt.com/api/mcp/v1/sse (replace with your actual URL).
3. Claude Code opens a browser tab for OAuth. Log into dbt Platform. Authorize.
4. Reload Claude Code. The Remote server is now listed under available MCP servers.

Claude Desktop and Cursor support remote MCP servers the same way; the UI varies but the steps are identical (URL, OAuth, reload).

Reload your MCP client. Then run this prompt in a fresh chat:

List the first 10 models in my dbt project using the dbt MCP.
Show me each model's name and its layer (staging, intermediate, mart).

If everything is wired up, what you should see is a tool call land, hit the dbt manifest, and return real model names from your project, something like this:

If nothing happens, or you see an error, jump to the troubleshooting section.

For a second smoke test:

Pick any mart model from my project. Show me its upstream lineage
and list the tests defined on it.

This exercises get_mart_models, get_model_lineage_dev, and get_test_details in a single conversation. If it works, your install is solid.

These are the prompts that earned the MCP its keep on the first few projects I ran it against. Copy them, run them on your project, watch what comes back. You will start adapting them within a day.

The MCP is only as good as the project it reads from. A few small things to fix first will dramatically improve what the agent can do:

• Parse cleanly. dbt parse with zero errors. The manifest is the agent’s source of truth. A broken parse means a stale or missing manifest, which means an agent guessing instead of reading.
• Tag primary keys. Models with explicit primary key columns (via unique tests or the new primary_key constraint) give the agent strong join inference. Without them, the agent guesses.
• Document at least your marts. Even one-line descriptions on each mart model and its key columns shift agent behavior from “looks at the SQL and guesses what this means” to “reads the description and reasons correctly.”
• Define sources properly. Use sources.yml. Avoid bare FROM raw.schema.table in SQL. The agent uses sources to answer “where does this data originally come from.”
• Name consistently. Stick to a convention (stg_, int_, fct_, dim_, mart_, whatever you have agreed on). The agent uses naming to infer layer structure. Inconsistent naming makes the inference noisy.
• Run dbt parse before any audit session. Re-parse if you have pulled new changes or switched branches. It takes seconds.

None of this is dbt MCP specific. It is good hygiene for any dbt project. The MCP just makes the cost of bad hygiene visible.

The first question any sensible data lead asks: what stops the agent from running dbt run --full-refresh on production at 2am?

The answer is layered. Use all three layers.

Layer 1: Per-tool permissions in Claude Code. Claude Code lets you decide which tools the agent can call automatically and which require a prompt. The pattern that works:

• Always allowed: get_all_models, get_mart_models, get_model_details, get_model_parents, get_model_lineage_dev, get_test_details, get_macro_details, get_seed_details, get_snapshot_details, list_metrics, get_dimensions, query_metrics.
• Requires prompt: any CLI tool (run, build, test, compile, clone), any codegen tool, any Admin API tool that triggers a job (trigger_job, retry_job).

Layer 2: Service token with minimum role. Generate the DBT_TOKEN under a service account with Developer role and read-only access to your production environment’s Discovery and Semantic Layer APIs. No job-trigger permission. The token literally cannot fire a run, no matter what the agent asks it to do.

Layer 3: Separate elevated session for writes. When you genuinely need to trigger a job or run a model, switch to a Claude Code profile with an elevated token, do the one task, switch back. Same pattern as sudo. The flip is intentional, which is the whole point.

The setup failure modes are predictable. If something is not working, scan this table first.

If you hit something that is not in this table, the dbt community Slack channel #tools-dbt-mcp is the right place to ask. dbt Labs engineers monitor it.