dbt-mcp

1.16.0 verified Fri May 01 auth: no python

A MCP (Model Context Protocol) server for interacting with dbt resources. Current version: 1.16.0. Released 2026-04-27. Follows semantic versioning with frequent releases (biweekly).

pip install dbt-mcp

Common errors

error ModuleNotFoundError: No module named 'dbt_mcp' ↓

cause Environment missing the dbt-mcp package or wrong Python environment active.

fix

Run pip install dbt-mcp in the correct environment.

error RuntimeError: DBT_CLOUD_ACCOUNT_ID environment variable not set ↓

cause Required environment variables not configured.

fix

Set DBT_CLOUD_ACCOUNT_ID and DBT_CLOUD_TOKEN (or DBT_CLOUD_API_KEY).

error TypeError: 'NoneType' object is not subscriptable ↓

cause Attempting to access tool result without checking if result is None, common when network issues occur.

fix

Check that the server is running and reachable, and handle None returns explicitly.

error ImportError: cannot import name 'MCPServer' from 'dbt_mcp' ↓

cause Wrong import path; `MCPServer` is in `dbt_mcp.server`.

fix

Use from dbt_mcp.server import MCPServer.

Warnings

breaking In v1.15.0, the `get_job_run_artifact` tool was removed. If you rely on it, pin to <1.15.0 or migrate to alternative tooling. ↓

fix Use `list_artifacts` and `get_artifact` (if available) or custom API calls.

breaking In v1.13.0, `get_project_details` tool was removed. Multi-project config now uses Admin API Client. ↓

fix Migrate to multi-project server config with `config_override` or use `list_projects`.

deprecated The `DBT_LSP_PATH` environment variable is deprecated in favor of built-in Fusion LSP support. Will be removed in future version. ↓

fix Remove `DBT_LSP_PATH`; use default Fusion LSP or editor storage paths.

gotcha Python 3.12+ required. The server will fail to start on Python <3.12. ↓

fix Ensure Python 3.12 or later.

gotcha If the `mcp.lock` file is a symbolic link, creation of FileLock may raise OSError on some systems. Fixed in v1.15.0 by resolving symlinks before locking. ↓

fix Upgrade to >=1.15.0 or avoid symlinked paths for `~/.dbt/mcp.lock`.

gotcha `list_metrics` response format changed from JSON to CSV in v1.15.1 to reduce payload size. Parsing code expecting JSON will break. ↓

fix Update metric parsing to handle CSV (or update to use new threshold `DBT_MCP_SL_FULL_CONFIG_THRESHOLD`).

Imports

MCPServer

wrong

from dbt_mcp import MCPServer

correct

from dbt_mcp.server import MCPServer

Incorrect direct import common in early docs.

Quickstart

Start a basic dbt MCP server. Requires dbt Cloud account ID and token set in environment.

import os
from dbt_mcp.server import MCPServer

server = MCPServer()
server.run()