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. It speaks MCP 2026-07-28 when the host can, and still accepts 2025-era initialize from spawn-stdio hosts. It is not an HTTP MCP server.

When to use MCP vs CLI

Use MCP	Use CLI instead
A 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

Canonical spawn (also used by the first-party MCP plugin):

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

Or a global dbt-tools-mcp binary:

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)

Plugin spawn (npx -y @dbt-tools/mcp). Bind an artifact root later with dbt_tools_set_target, or add --dbt-target in args:

{
  "mcpServers": {
    "dbt-tools": {
      "command": "npx",
      "args": ["-y", "@dbt-tools/mcp"]
    }
  }
}

Global binary (dbt-tools-mcp) with an initial 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