🤫 dbt-mshhcp-setup

The simple and silent dbt MCP configurator for VS Code.

Sets up the dbt MCP server in your VS Code workspace without touching your existing environment. A step-by-step wizard asks for confirmation at every stage — it never modifies anything without your explicit approval.

This project doesn't reinvent the wheel, nor is it full of innovations and glitz. It just does what it needs to do without any fuss.

What it does

Generates a .vscode/mcp.json file that connects GitHub Copilot (and other MCP clients in VS Code) to your local dbt project via the dbt-mcp server. The configuration is minimal and secure by design:

• Only dbt CLI tools are enabled (DBT_MCP_ENABLE_DBT_CLI=true) — dbt run, build, test, compile, list, parse, show, and lineage queries.
• All platform features are disabled — Semantic Layer, Discovery API, Admin API, SQL execution, Codegen, and LSP stay off. This is achieved via dbt's enable-mode allowlist: setting any DBT_MCP_ENABLE_* variable activates allowlist mode, so only explicitly enabled toolsets are available — including any new ones added in future dbt-mcp versions.
• Existing configs are never silently overwritten — if mcp.json already exists, the wizard shows the current servers and asks whether to add a new one.

Requirements

Supported platforms: Ubuntu 24.04, Windows 11, Windows 11 (WSL 2).

Quick start

No clone required. Run directly with uvx:

uvx dbt-mshhcp-setup

The wizard walks you through 7 steps:

  ┌─────┐ ┌─────┐ ┌─────┐
  │  d  ├─┤  b  ├─┤  t  │   🤫  shhh...
  └─────┘ └─────┘ └─────┘
  dbt-mshhcp-setup · v0.1.0
  The silent dbt MCP configurator

[1/6] Checking prerequisites...
  ✓ uv 0.7.x found

[2/6] Target workspace
  ? Path to your VS Code workspace: /home/you/my-repo
  ✓ .vscode directory found

[3/6] Checking existing configuration...
  ✓ No existing mcp.json — ready to configure

[4/6] Configure server(s)
  --- Server 1 ---
  ? Server name (e.g. dbt-databricks): dbt-databricks
  ? Path to dbt project (folder containing dbt_project.yml): /home/you/my-repo/dbt_project
  ✓ dbt project found.
  Environment loading method:
    1) direnv
    2) --env-file  (recommended by dbt)
    3) None  (direct uvx)
  ? Select [3]: 2
  ? Absolute path to .env file: /home/you/my-repo/dbt_project/.env
  ℹ Auto-detected DBT_PATH: /home/you/my-repo/dbt_project/.venv/bin/dbt
  ? DBT_PATH [/home/you/my-repo/dbt_project/.venv/bin/dbt]:
  ? DBT_CLI_TIMEOUT (seconds) [180]:
  ✓ Server 'dbt-databricks' configured.

  ? Add another server? [y/N]: n

[5/6] Review

  Configuration preview (1 server(s)):

  {
    "servers": {
      "dbt-databricks": {
        "command": "uvx",
        "args": ["--env-file", "/home/you/my-repo/dbt_project/.env", "dbt-mcp"],
        "env": {
          "DBT_PROJECT_DIR": "/home/you/my-repo/dbt_project",
          "DBT_PATH": "/home/you/my-repo/dbt_project/.venv/bin/dbt",
          "DBT_CLI_TIMEOUT": "180",
          "DBT_MCP_ENABLE_DBT_CLI": "true"
        }
      }
    }
  }

  ℹ Only dbt CLI tools are enabled (DBT_MCP_ENABLE_DBT_CLI=true).
     All platform features (Semantic Layer, Discovery, Admin API, etc.) are disabled.

  ? Write to /home/you/my-repo/.vscode/mcp.json? [Y/n]: Y
  ✓ Written to /home/you/my-repo/.vscode/mcp.json

[6/6] Smoke test
  Validating paths and checking uvx can resolve dbt-mcp...
  ✓ All paths valid.
  ✓ dbt-mcp is available via uvx.

[7/7] Copilot awareness (optional)
  ? Configure Copilot to be aware of this dbt MCP setup? [y/N]: y
  ? Default production schema for 'dbt-databricks' (e.g. analytics.marts): analytics.marts
  Delivery method:
    1) Instructions file  (automatic — Copilot applies when relevant)
    2) Reusable prompt file  (manual — /server-name per session)
    3) Skip
  ? Select [1]: 1
  ✓ Written: /home/you/.copilot/instructions/dbt-mcp.instructions.md

✓ All done! Restart VS Code to activate the MCP server(s).

How it works

flowchart TD
    START([uvx dbt-mshhcp-setup]) --> S1

    subgraph S1 ["[1/6] Prerequisites"]
        UV{uv installed?}
        UV -- Yes --> UV_OK([✓ continue])
        UV -- No --> UV_PROMPT{Install uv now?}
        UV_PROMPT -- No --> E1([Exit])
        UV_PROMPT -- Yes --> UV_INSTALL[Run installer]
        UV_INSTALL --> UV_CHECK{Installed OK?}
        UV_CHECK -- No --> E2([Exit])
        UV_CHECK -- Yes --> UV_OK
    end

    S1 --> S2

    subgraph S2 ["[2/6] Target workspace"]
        WS[Prompt workspace path]
        WS --> WS_DIR{Directory exists?}
        WS_DIR -- No --> WS
        WS_DIR -- Yes --> VSCODE{.vscode/ exists?}
        VSCODE -- Yes --> VSCODE_OK([✓ continue])
        VSCODE -- No --> VSCODE_CREATE{Create .vscode/?}
        VSCODE_CREATE -- No --> E3([Exit])
        VSCODE_CREATE -- Yes --> MKDIR[mkdir .vscode/]
        MKDIR --> VSCODE_OK
    end

    S2 --> S3

    subgraph S3 ["[3/6] Existing configuration"]
        MCP{mcp.json exists?}
        MCP -- No --> MCP_FRESH([✓ fresh config])
        MCP -- Yes --> MCP_SHOW[Show existing servers]
        MCP_SHOW --> MCP_ADD{Add a new server?}
        MCP_ADD -- No --> E4([Exit — no changes])
        MCP_ADD -- Yes --> MCP_FRESH
    end

    S3 --> S4

    subgraph S4 ["[4/6] Configure server(s)"]
        NAME[Prompt server name]
        NAME --> NAME_OK{Valid & unique?}
        NAME_OK -- No --> NAME
        NAME_OK -- Yes --> PROJ[Prompt dbt project path]
        PROJ --> PROJ_OK{"dbt_project.yml\nfound?"}
        PROJ_OK -- No --> PROJ
        PROJ_OK -- Yes --> ENV[Prompt env loading mode]
        ENV --> ENV_CHOICE{Mode?}
        ENV_CHOICE -- direnv --> DIRENV[Prompt direnv exec path]
        ENV_CHOICE -- env-file --> ENVFILE[Prompt .env file path]
        ENV_CHOICE -- direct --> DBTPATH
        DIRENV --> DBTPATH[Auto-detect DBT_PATH]
        ENVFILE --> DBTPATH
        DBTPATH --> DBTPATH_CONFIRM[Confirm / override path]
        DBTPATH_CONFIRM --> TIMEOUT[Prompt timeout]
        TIMEOUT --> ANOTHER{Add another server?}
        ANOTHER -- Yes --> NAME
        ANOTHER -- No --> S4_DONE([✓ servers collected])
    end

    S4 --> S5

    subgraph S5 ["[5/6] Review & write"]
        PREVIEW[Show JSON preview]
        PREVIEW --> SEC_NOTE["ℹ DBT_MCP_ENABLE_DBT_CLI=true\nAll platform features disabled"]
        SEC_NOTE --> WRITE_Q{Write mcp.json?}
        WRITE_Q -- No --> E5([Exit — no changes])
        WRITE_Q -- Yes --> WRITE[Write .vscode/mcp.json]
        WRITE --> S5_DONE([✓ written])
    end

    S5 --> S6

    subgraph S6 ["[6/6] Smoke test"]
        TEST_PATHS[Validate all paths exist]
        TEST_PATHS --> UVX_AVAIL{uvx in PATH?}
        UVX_AVAIL -- No --> WARNS
        UVX_AVAIL -- Yes --> TEST_UVX[Check uvx resolves dbt-mcp]
        TEST_UVX --> WARNS{Any warnings?}
        WARNS -- Yes --> SHOW_WARN[Print warnings]
        WARNS -- No --> ALL_OK[All checks passed]
        SHOW_WARN --> DONE_WARN([Done — review warnings])
        ALL_OK --> DONE([✓ All done!])
    end

Environment loading modes

Each server can load environment variables (database credentials, profiles, etc.) in one of three ways:

The database credentials themselves live in your .env or direnv setup — dbt-mshhcp-setup never reads, stores, or prints them.

Multiple dbt projects

You can configure more than one server in a single run (e.g. one for Databricks, one for BigQuery). Each server gets its own entry in mcp.json:

{
  "servers": {
    "dbt-databricks": {
      "command": "direnv",
      "args": ["exec", "/home/you/data-platform/dbt_project", "uvx", "dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/home/you/data-platform/dbt_project",
        "DBT_PATH": "/home/you/data-platform/dbt_local_run/.venv/bin/dbt",
        "DBT_CLI_TIMEOUT": "180",
        "DBT_MCP_ENABLE_DBT_CLI": "true"
      }
    },
    "dbt-bigquery": {
      "command": "uvx",
      "args": ["--env-file", "/home/you/people-analytics/.env", "dbt-mcp"],
      "env": {
        "DBT_PROJECT_DIR": "/home/you/people-analytics",
        "DBT_PATH": "/home/you/people-analytics/.venv/bin/dbt",
        "DBT_CLI_TIMEOUT": "180",
        "DBT_MCP_ENABLE_DBT_CLI": "true"
      }
    }
  }
}

If mcp.json already exists with servers you configured earlier, re-running the wizard offers to add a new server — it will not touch the existing entries.

WSL 2 notes

mcp.json (steps 1–6): The wizard always writes to the workspace .vscode/mcp.json, which is the correct location for WSL. VS Code user settings do not work for MCP in WSL — workspace settings do. See the dbt VS Code integration docs for details.

Copilot awareness (step 7): Method 1 writes to ~/.copilot/instructions/dbt-mcp.instructions.md — a standard user-level path that VS Code reads automatically on all platforms (Linux, Windows, WSL). No path detection needed. Method 2 (reusable prompt file) still requires detecting the VS Code user directory; when WSL is detected, the tool tries ~/.config/Code/User/ first (VS Code Server in WSL), then /mnt/c/Users/<user>/AppData/Roaming/Code/User/ (VS Code for Windows), with a manual fallback.

Development

git clone https://github.com/your-org/dbt-mshhcp-setup
cd dbt-mshhcp-setup
uv sync          # creates .venv, installs runtime + dev deps, generates uv.lock
uv run pytest    # run tests
uv run dbt-mshhcp-setup  # run the wizard locally

Project structure

dbt-mshhcp-setup/
├── pyproject.toml                    # deps, build config, entry point
├── uv.lock                           # reproducible dependency lock (commit this)
├── .python-version                   # pins Python 3.10
└── src/
    └── dbt_mshhcp_setup/
        ├── __init__.py               # __version__
        ├── cli.py                    # interactive wizard (7 steps)
        ├── config.py                 # build / read / write mcp.json
        ├── checks.py                 # uv detection, path validation, smoke test
        └── copilot.py               # VS Code Copilot awareness (step 7)

What is NOT in scope

This tool is intentionally minimal. It does not:

• Configure dbt platform / dbt Cloud features (Semantic Layer, Discovery API, OAuth)
• Set up or scaffold dbt projects
• Manage database credentials
• Modify VS Code settings.json

For full dbt MCP documentation, see docs.getdbt.com/docs/dbt-ai.