Local and remote artifacts

dbt-tools is local-first: the default path is a dbt target/ directory on disk. Remote object storage is supported when you explicitly configure it—credentials stay on the Node side, not in the browser.

Modes

Mode	Typical use
Local target/	Developer loop, CI artifact download, dbt-tools-web --dbt-target or --target
Remote S3/GCS	Investigating scheduled runs in a bucket (s3://…, gs://… as --dbt-target)
Web upload / preload	Ad hoc files or trusted local preload in the UI (server-mediated)

Target URIs (CLI and MCP)

# Local
dbt-tools status --dbt-target ./target

# S3 — scheme required (unschemed paths are treated as local)
dbt-tools status --dbt-target s3://my-bucket/dbt/prod

# GCS
dbt-tools status --dbt-target gs://my-bucket/dbt/prod

Required objects at the prefix root: manifest.json and run_results.json (same contract as local target/).

Credentials (Node only)

Configure the CLI, MCP, or web server process—not the browser.

Provider	Typical setup
S3	AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY, AWS_PROFILE, or instance role; optional DBT_TOOLS_S3_REGION, DBT_TOOLS_S3_ENDPOINT
GCS	GOOGLE_APPLICATION_CREDENTIALS or application default credentials; optional DBT_TOOLS_GCS_PROJECT_ID

GCS impersonation (read-only)

For gs:// targets, use a dedicated service account via impersonation (read-only access):

Setting	CLI / MCP / Web
DBT_TOOLS_GCS_IMPERSONATE_SERVICE_ACCOUNT	Service account email to impersonate (gs:// only)
DBT_TOOLS_GCS_PROJECT_ID	GCP project ID for the GCS client
--gcs-impersonate-service-account	Same as env; set at MCP or web server startup (not via MCP set_target)

MCP client example:

{
  "mcpServers": {
    "dbt-tools": {
      "command": "npx",
      "args": ["-y", "@dbt-tools/mcp", "--dbt-target", "gs://my-bucket/dbt/prod"],
      "env": {
        "DBT_TOOLS_GCS_PROJECT_ID": "my-gcp-project",
        "DBT_TOOLS_GCS_IMPERSONATE_SERVICE_ACCOUNT": "reader@my-project.iam.gserviceaccount.com"
      }
    }
  }
}

CLI: the same DBT_TOOLS_* variables apply for gs:// targets—see Configuration.

CLI and MCP

• Pass --dbt-target or DBT_TOOLS_DBT_TARGET to a directory or remote URI.
• status checks filesystem or downloaded copies before parse-heavy commands.
• Large remote manifests benefit from MCP resident cache when agents issue many queries.

Web

dbt-tools-web uses the same startup flags as MCP for artifact root and remote clients (--dbt-target, --gcs-impersonate-service-account, --s3-region, etc.). See Web server CLI.

• --dbt-target / DBT_TOOLS_DBT_TARGET — preload local, s3://, or gs:// at server start.
• --target / DBT_TOOLS_TARGET_DIR — local directory alias (backward compatible).
• Load artifacts (in-app) — switch or add sources after startup; UI can pass GCS impersonation per request. Env DBT_TOOLS_GCS_* / DBT_TOOLS_S3_* also apply when discovering remote sources.

Credentials stay on the Node process; the browser uses /api/... routes only. See Web getting started.

Web server example (GCS):

npx @dbt-tools/web \
  --dbt-target gs://my-bucket/dbt/prod \
  --gcs-project-id my-gcp-project \
  --gcs-impersonate-service-account reader@my-project.iam.gserviceaccount.com

Learn more

• Configuration
• MCP tools
• Troubleshooting — remote and empty target issues