Set up local MCP beta

The local dbt MCP server runs locally on your machine. Set up the local dbt MCP server with the following directions:

1. Install uv to be able to run dbt-mcp and related dependencies into an isolated virtual environment.

2. Create an .env file to set your environment variables. You will need to configure environment variables to access the tools. If you are only using the dbt CLI commands, you do not need to supply the dbt platform-specific environment variables, and vice versa.

   Sample file

   Here is an example of the file:

   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_ACCOUNT_ID=your-account-id
   DBT_TOKEN=your-service-token
   DBT_PROJECT_DIR=/path/to/your/dbt/project
   DBT_PATH=/path/to/your/dbt/executable
   MULTICELL_ACCOUNT_PREFIX=your-account-prefix

   You will need this file for integrating with MCP-compatible tools.

   API and SQL tool settings

   Environment Variable	Required	Description
   DBT_HOST	Required	Your dbt platform instance hostname. If you're using Multi-cell, exclude the ACCOUNT_PREFIX from the hostname. The default is cloud.getdbt.com
   MULTICELL_ACCOUNT_PREFIX	Only required for Multi-cell instances	Set your Multi-cell ACCOUNT_PREFIX. If you are not using Multi-cell, don't set this value. You can learn more about regions and hosting here.
   DBT_TOKEN	Required	Your personal access token or service token from the dbt platform. Note: When using the Semantic Layer, it is recommended to use a personal access token. If you're using a service token, make sure that it has at least Semantic Layer Only, Metadata Only, and Developer permissions.
   DBT_ACCOUNT_ID	Required for Admininstrative API tools	Your dbt account ID
   DBT_PROD_ENV_ID	Required	Your dbt Cloud production environment ID
   DBT_DEV_ENV_ID	Optional	Your dbt Cloud development environment ID
   DBT_USER_ID	Optional	Your dbt Cloud user ID (docs)

   dbt CLI settings

   The local dbt-mcp supports all flavors of dbt, including dbt Core and the dbt Fusion engine.

   Environment Variable	Required	Description	Example
   DBT_PROJECT_DIR	Required	The path to where the repository of your dbt project is hosted locally.	/Users/myname/reponame
   DBT_PATH	Required	The path to your dbt executable (Core/Fusion/Cloud CLI). You can find your dbt executable by running which dbt	/opt/homebrew/bin/dbt
   DBT_CLI_TIMEOUT	Optional	Configure the number of seconds before your agent will timeout dbt CLI commands.	Defaults to 10 seconds.

   You can set any environment variable supported by your dbt executable, like for the ones supported in dbt Core.

   DBT_WARN_ERROR_OPTIONS='{"error": ["NoNodesForSelectionCriteria"]}' is automatically set so that the MCP server knows if no node is selected when running a dbt command. You can overwrite it if needed, but it provides a better experience when calling dbt from the MCP server, ensuring the tool selects valid nodes.

   Disabling tools

   You can disable the following tool access on the local dbt-mcp:

   Name	Default	Description
   DISABLE_DBT_CLI	false	Set this to true to disable dbt Core, dbt Cloud CLI, and dbt Fusion MCP tools
   DISABLE_SEMANTIC_LAYER	false	Set this to true to disable dbt Semantic Layer MCP tools
   DISABLE_DISCOVERY	false	Set this to true to disable dbt Discovery API MCP tools
   DISABLE_ADMIN_API	false	Set this to true to disable dbt Admininistrative API MCP tools
   DISABLE_SQL	true	Set this to false to enable SQL MCP tools
   DISABLE_TOOLS	""	Set this to a list of tool names delimited by a , to disable specific tools

3. (Optional) Test your configuration:

   In a terminal, run the following command to test your setup:

   uvx --env-file <path-to-.env-file> dbt-mcp

   If there are no errors, uv and the .env file are set up correctly and you can move on to the next step.

4. Set up your MCP client:

   After creating your .env file, you can move on to our guides on connecting dbt-mcp to tools like Claude Desktop or Cursor or to creating aconfiguration file. This is dependent on what tools you want to integrate with.

   Example configuration

   For some tools, you may need an additional configuration file to upload to connect to dbt-mcp. Here is a sample configuration JSON file that you can use to connect to the MCP tools. Be sure to replace the sections within <>:

   {
     "mcpServers": {
       "dbt-mcp": {
         "command": "uvx",
         "args": [
           "--env-file",
           "<path-to-.env-file>",
           "dbt-mcp"
         ]
       }
     }
   }

   <path-to-.env-file> is where you saved the .env file from the Setup step.

Was this page helpful?

Privacy policyCreate a GitHub issue

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.