Connecting MCP clients

dbt-tools-mcp is a stdio MCP server. It keeps a dbt artifact run parsed in memory so clients can issue many small queries without reloading large manifests on every call.

When to use MCP vs CLI

Use MCP	Use CLI instead
An AI coding agent issues many tool calls on the same run	One-shot shell or CI command
Parse cost dominates (large manifest, remote target)	Simple status or summary check

Skills from Install agent skills run the CLI on your machine. MCP is optional for native MCP tool integration.

Launch

npx @dbt-tools/mcp --dbt-target ./target

Or global install:

npm install -g @dbt-tools/mcp
dbt-tools-mcp --dbt-target ./target

Set DBT_TOOLS_DBT_TARGET so client configs can omit the flag.

Optional cache tuning (long sessions, multiple tag slices):

export DBT_TOOLS_MAX_CACHED_TARGETS=3   # default; 0 disables in-memory cache
export DBT_TOOLS_CACHE_TTL_MS=0          # idle eviction; 0 = disabled

Client configuration (pattern)

Point your MCP client at the dbt-tools-mcp binary with the same artifact root:

{
  "mcpServers": {
    "dbt-tools": {
      "command": "dbt-tools-mcp",
      "args": [
        "--dbt-target",
        "./target",
        "--max-cached-targets",
        "3",
        "--poll-interval-ms",
        "30000"
      ]
    }
  }
}

Omit --max-cached-targets and --cache-ttl-ms to use defaults (3 cached roots, TTL disabled). Exact config file location depends on your editor—see your MCP host documentation.

Lifecycle tools: MCP tools (dbt_tools_set_target, dbt_tools_unset_target, dbt_tools_clear_cached_targets).

Learn more

• Getting started
• Configuration
• Troubleshooting — MCP stdio issues
• MCP README