How to add dbt MCP Server to Windsurf

Give AI agents context of your dbt project — run dbt CLI, query the Semantic Layer, explore lineage, and manage jobs. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 584★ · stdio · apikey

Windsurf config for dbt MCP Server

uvx dbt-mcp

{
  "mcpServers": {
    "dbt-mcp-server": {
      "command": "uvx",
      "args": [
        "dbt-mcp"
      ],
      "env": {
        "DBT_HOST": "cloud.getdbt.com",
        "DBT_PROD_ENV_ID": "your-production-environment-id",
        "DBT_DEV_ENV_ID": "your-development-environment-id",
        "DBT_USER_ID": "your-user-id",
        "DBT_TOKEN": "your-service-token-or-pat",
        "DBT_PROJECT_DIR": "/path/to/your/dbt/project",
        "DBT_PATH": "/path/to/your/dbt/executable"
      }
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the dbt MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5dbt MCP Server's tools become available to Cascade.

Before you start

uv / uvx installed (for the local stdio server)
Python 3.12 or 3.13 (3.12 <= version < 3.14)
For dbt Platform features: a dbt Platform account, host (DBT_HOST), a service token or Personal Access Token (DBT_TOKEN), and the relevant environment IDs
For local dbt CLI tools: a dbt project directory (DBT_PROJECT_DIR) and a dbt executable path (DBT_PATH)

What dbt MCP Server can do in Windsurf

execute_sql

Executes SQL on dbt Platform infrastructure with Semantic Layer support.

text_to_sql

Generates SQL from natural language using project context.

get_dimension_values

Gets distinct values for a dimension; option to scope to specific metrics.

get_dimensions

Gets dimensions for specified metrics.

get_entities

Gets entities for specified metrics.

get_metrics_compiled_sql

Returns compiled SQL for metrics without executing the query.

list_metrics

Retrieves all defined Semantic Layer metrics.

list_saved_queries

Retrieves all saved queries.

Security

Enabling the dbt CLI tools lets the client run dbt commands (build, run, clone, etc.) that can modify your data models, sources, and warehouse objects — only enable them for clients you trust. The dbt Platform tools require a service token or Personal Access Token (DBT_TOKEN); the execute_sql tool specifically requires a PAT plus dev environment and user IDs. Store tokens via environment variables or an env file rather than committing them. SQL, Codegen, and server-metadata tool groups are disabled by default and must be explicitly enabled.

dbt MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the dbt MCP Server config there under the "mcpServers" key and restart the client.

Is dbt MCP Server safe to use with Windsurf?

How do I install and run the dbt MCP server?

Install uv, then run it via `uvx dbt-mcp` — no need to clone the repo unless you are contributing. Configure it in your MCP client (Claude, Cursor, VS Code) as a stdio server with the appropriate environment variables.

Does it work with dbt Core or only dbt Platform?

Both. It works with dbt Core, dbt Fusion, and the dbt Platform. Local dbt CLI tools need DBT_PROJECT_DIR and DBT_PATH, while Semantic Layer, Discovery, and Admin API tools require dbt Platform credentials (DBT_HOST and DBT_TOKEN).

Is there a hosted/remote option?

Yes. In addition to the local stdio server, dbt offers a remote HTTP MCP server hosted on the dbt Platform that connects over a URL with token-based or OAuth authentication, so no local installation is required.

View repo Full dbt MCP Server page