### Install Dependencies

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ai_sdk_agent/README.md

Install project dependencies using npm.

```bash
npm install
```

--------------------------------

### Start Local MCP Server

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ai_sdk_agent/README.md

Start the dbt MCP server for local use.

```bash
npm run start:local
```

--------------------------------

### Example Usage

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/admin_api/get_job_run_artifact.md

Examples of how to specify the artifact path and optionally the step.

```json
{
  "run_id": 789,
  "artifact_path": "manifest.json"
}
```

```json
{
  "run_id": 789,
  "artifact_path": "compiled/analytics/models/staging/stg_users.sql"
}
```

```json
{
  "run_id": 789,
  "artifact_path": "run_results.json",
  "step": 2
}
```

--------------------------------

### Start Remote MCP Server

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ai_sdk_agent/README.md

Start the dbt MCP server for remote use.

```bash
npm start
```

--------------------------------

### Server Setup

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/API_INDEX.md

Example of setting up and running the dbt-mcp server.

```python
from dbt_mcp.config.config import load_config
from dbt_mcp.mcp.server import create_dbt_mcp
import asyncio

async def main():
    config = load_config()
    server = await create_dbt_mcp(config)
    server.run(transport="stdio")

asyncio.run(main())
```

--------------------------------

### Get Node Details (Development) Examples

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/dbt_cli/get_node_details_dev.md

Examples of how to call the `get_node_details_dev` function with different node identifiers.

```python
get_node_details_dev(node_id="stg_zip__invoices")
get_node_details_dev(node_id="model.my_project.stg_zip__invoices")
get_node_details_dev(node_id="seed.my_project.country_codes")
```

--------------------------------

### Quick Start Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/README.md

A Python script demonstrating how to load configuration, create the dbt-mcp server, list tools, and call a tool.

```python
from dbt_mcp.config.config import load_config
from dbt_mcp.mcp.server import create_dbt_mcp
from dbt_mcp.errors.base import ToolCallError
import asyncio

async def main():
    # Load configuration from environment
    config = load_config()
    
    # Create the MCP server
    server = await create_dbt_mcp(config)
    
    # List all available tools
    tools = await server.list_tools()
    print(f"Available tools: {len(tools)}")
    
    # Call a tool
    try:
        result = await server.call_tool(
            "get_all_models",
            {}
        )
        print(f"Result: {result}")
    except ToolCallError as e:
        print(f"Error: {e}")

if __name__ == "__main__":
    asyncio.run(main())
```

--------------------------------

### Get Exposure Details Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_exposure_details.md

Example of how to retrieve details for an exposure using its unique ID.

```python
get_exposure_details(unique_id="exposure.analytics.customer_dashboard")
```

--------------------------------

### Usage

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/openai_responses/README.md

Command to run the example.

```bash
uv run main.py
```

--------------------------------

### Run the multi-agent example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ag2_agent/README.md

Executes the main_multiagent.py script for a multi-agent setup using dbt Cloud.

```bash
uv run main_multiagent.py
```

--------------------------------

### Example 1: Get all dimensions for a metric

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/semantic_layer/get_dimensions.md

This example demonstrates how to retrieve all available dimensions for the 'revenue' metric when the user is interested in general analysis trends.

```python
Parameters:
    metrics=["revenue"]
    search=null
```

--------------------------------

### Environment Setup Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Bash commands to set environment variables required for dbt-mcp CLI and codegen tools.

```bash
export DBT_PROJECT_DIR=/path/to/my/dbt/project
export DBT_PATH=/path/to/dbt
export DBT_CLI_TIMEOUT=120
```

--------------------------------

### Run the single agent, local example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ag2_agent/README.md

Executes the main_stdio.py script for a single agent setup running locally.

```bash
uv run main_stdio.py
```

--------------------------------

### Example usage of load_config

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/configuration.md

Example of how to load the configuration and access dbt CLI settings.

```python
from dbt_mcp.config.config import load_config

config = load_config()
print(f"dbt Path: {config.dbt_cli_config.dbt_path}")
print(f"Project Dir: {config.dbt_cli_config.project_dir}")
```

--------------------------------

### Test Output Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

An example of the output from the comprehensive test suite, showing successful environment setup, tool imports, and overall test completion.

```text
🚀 Complete Tool and Agent Test Suite
==================================================
🔧 Testing Environment Setup
------------------------------
  ✅ DBT_MCP_URL: https://your-mcp-server.com
  ✅ DBT_TOKEN: ****************
  ✅ DBT_USER_ID: your_user_id
  ✅ DBT_PROD_ENV_ID: your_env_id
  ✅ Environment setup complete!

📦 Testing Tool Imports
------------------------------
  ✅ All tools imported successfully
  ✅ dbt_compile is callable
  ✅ dbt_mcp_tool is callable
  ✅ dbt_model_analyzer_agent is callable

... (more tests)

🎉 All tests passed! Your agent and tools are working correctly.

```

--------------------------------

### DefaultSemanticLayerClientProvider Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/semantic_layer_client.md

Example usage of DefaultSemanticLayerClientProvider to get a Semantic Layer client.

```python
from dbt_mcp.semantic_layer.client import DefaultSemanticLayerClientProvider
from dbt_mcp.config.config_providers import SemanticLayerConfig

provider = DefaultSemanticLayerClientProvider()
# Assuming config is prepared with environment_id, token, and host
client = await provider.get_client(config=semantic_layer_config)
```

--------------------------------

### Example Usage of list_jobs

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/admin_api_client.md

Example of how to list jobs for an account and print their names and statuses.

```python
from dbt_mcp.dbt_admin.client import DbtAdminAPIClient

client = DbtAdminAPIClient(config_provider)
jobs = await client.list_jobs(account_id=123, project_id=456)
for job in jobs:
    print(f"Job: {job['name']} (ID: {job['id']})")
    print(f"  Status: {job.get('most_recent_run_status')}")
```

--------------------------------

### Example usage of list_tools

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/mcp_server.md

An example demonstrating how to create a dbt MCP server instance and list its available tools, printing their names and descriptions.

```python
from dbt_mcp.mcp.server import create_dbt_mcp
from dbt_mcp.config.config import load_config
import asyncio

async def list_tools():
    config = load_config()
    server = await create_dbt_mcp(config)
    tools = await server.list_tools()
    for tool in tools:
        print(f"Tool: {tool.name} - {tool.description}")

asyncio.run(list_tools())
```

--------------------------------

### Run the single agent, dbt Cloud example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ag2_agent/README.md

Executes the main_remote.py script for a single agent setup using dbt Cloud.

```bash
uv run main_remote.py
```

--------------------------------

### Usage Pattern - Multi Project

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/credentials_and_providers.md

Example of using a multi-project configuration provider.

```python
# Create multi-project provider
multi_provider = MultiProjectDiscoveryConfigProvider(
    credentials_provider=inner,
    admin_client=admin_client
)

# Get project-specific configuration
config = await multi_provider.get_config(project_id=123)
```

--------------------------------

### Usage Pattern - Single Project

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/credentials_and_providers.md

Example of using a single project configuration provider.

```python
from dbt_mcp.config.credentials import CredentialsProvider
from dbt_mcp.config.settings import DbtMcpSettings

# Create credentials provider
inner = CredentialsProvider(settings)

# Create service-specific provider
discovery_provider = DefaultDiscoveryConfigProvider(inner)

# Get configuration when needed
config = await discovery_provider.get_config()

# Use configuration
discovery_client = await semantic_layer_client.get_client(config=config)
```

--------------------------------

### Set up environment variables

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

Copies the example environment file and instructs to edit it.

```bash
cp .env.example .env
# Edit .env with your configuration
```

--------------------------------

### Usage Examples

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_lineage.md

Examples demonstrating how to use the get_lineage function with different parameters.

```python
# Get complete lineage (all connected nodes, all types, default depth of 5)
get_lineage(unique_id="model.analytics.customers")

# Get lineage filtered to only models and sources
get_lineage(unique_id="model.analytics.customers", types=["Model", "Source"])

# Get only immediate neighbors (depth=1)
get_lineage(unique_id="model.analytics.customers", depth=1)

# Get deeper lineage for comprehensive analysis
get_lineage(unique_id="model.analytics.customers", depth=10)
```

--------------------------------

### Example usage of create_dbt_mcp

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/mcp_server.md

An example demonstrating how to load configuration, create a dbt MCP server instance, and run it with stdio transport.

```python
from dbt_mcp.config.config import load_config
from dbt_mcp.mcp.server import create_dbt_mcp
import asyncio

async def setup_server():
    config = load_config()
    server = await create_dbt_mcp(config)
    server.run(transport="stdio")
    
asyncio.run(setup_server())
```

--------------------------------

### Get warnings only

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/admin_api/get_job_run_error.md

Example JSON payload to retrieve only warning information for a specific job run.

```json
{
  "run_id": 789,
  "warning_only": true
}
```

--------------------------------

### Google Model Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ai_sdk_agent/README.md

Example of configuring the AI SDK to use a Google model.

```typescript
// Google
import { google } from "@ai-sdk/google";
const model = google("gemini-2.0-flash");
```

--------------------------------

### Example Request Body

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/admin_api/get_job_run_details.md

This JSON object represents the request body to get details for a specific dbt job run.

```json
{
  "run_id": 789
}
```

--------------------------------

### Defining a new tool

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/CONTRIBUTING.md

Example of how to define a new tool with its description, title, and hints.

```python
    @dbt_mcp_tool(
        description=get_prompt("category/tool_name"),
        title="My Tool",
        read_only_hint=True,
        destructive_hint=False,
        idempotent_hint=True,
    )
    async def my_tool(context: MyToolContext, param: str) -> dict:
        return await context.fetcher.do_something(param)
```

--------------------------------

### Running with State Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Python code example for running dbt commands comparing current state to a previous run using 'state_path'.

```python
result = await dbt_mcp.call_tool(
    "run",
    {
        "node_selection": "state:modified",
        "state_path": "/path/to/previous/manifest.json"
    }
)
```

--------------------------------

### Example Request Body

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/admin_api/get_project_details.md

A JSON object representing the request body to get details for a specific dbt Cloud project.

```json
{
  "project_id": 123
}
```

--------------------------------

### dbt Compile Tool Usage Examples

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

Example user prompts for the dbt Compile Tool.

```text
> "Compile my dbt project and find any issues"
> "What's wrong with my models in the staging folder?"
```

--------------------------------

### Example Selection

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Examples of how to use the node_selection parameter for selecting dbt resources.

```python
# Select specific models
node_selection="path:models/marts models/core"
```

```python
# Select by tag
node_selection="tag:daily"
```

```python
# Select by package
node_selection="package:dbt_utils"
```

```python
# Exclude tests
node_selection="*,--exclude=resource_type:test"
```

--------------------------------

### dbt MCP Server Tool Usage Examples

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

Example user prompts for the dbt MCP Server Tool.

```text
> "List all available dbt MCP tools"
> "Show me the catalog from dbt Cloud"
> "Run my models in dbt Cloud"
> "What tests are available in my dbt project?"
```

--------------------------------

### Making Tool Calls

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/API_INDEX.md

Examples of listing available tools and calling a specific tool.

```python
# List available tools
tools = await server.list_tools()

# Call a tool
result = await server.call_tool(
    "get_all_models",
    {}
)
```

--------------------------------

### Configure environment variables

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/CONTRIBUTING.md

Command to copy the example environment file and a note to edit it with specific variables.

```shell
cp .env.example .env
```

--------------------------------

### list_metrics Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/semantic_layer_client.md

Example of listing metrics using SemanticLayerFetcher, optionally filtering by search terms.

```python
from dbt_mcp.semantic_layer.client import SemanticLayerFetcher, DefaultSemanticLayerClientProvider

fetcher = SemanticLayerFetcher(DefaultSemanticLayerClientProvider())
response = await fetcher.list_metrics(config, search="revenue")
for metric in response.metrics:
    print(f"Metric: {metric.name} ({metric.type})")
```

--------------------------------

### Fetch a test by unique_id

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_test_details.md

This example shows how to fetch a dbt test using its unique identifier.

```python
get_test_details(unique_id="test.analytics.is_empty_string")
```

--------------------------------

### Basic Node Selection

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/dbt_cli/args/node_selection.md

Examples of selecting individual models.

```bash
my_model
```

--------------------------------

### Example Usage of ConfigurationError

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/errors.md

Example of how to catch a ConfigurationError.

```python
from dbt_mcp.errors.common import ConfigurationError

try:
    # Load config without required env vars
    config = load_config()
except ConfigurationError as e:
    print(f"Configuration error: {e}")
```

--------------------------------

### dbt CLI Commands

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/API_INDEX.md

Examples of executing dbt commands like 'run' and 'generate_source' through the tool interface.

```python
# Execute dbt run
result = await dbt_mcp.call_tool(
    "run",
    {
        "node_selection": "models/marts/*",
        "vars": '{"env": "prod"}'
    }
)

# Generate source YAML
yaml = await dbt_mcp.call_tool(
    "generate_source",
    {
        "schema_name": "raw",
        "source_name": "raw",
        "include_columns": True
    }
)
```

--------------------------------

### Install dependencies

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

Installs project dependencies using pip.

```bash
pip install -r requirements.txt
```

--------------------------------

### Running with Variables Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Python code example for passing dbt variables to models using the 'vars' parameter.

```python
result = await dbt_mcp.call_tool(
    "run",
    {
        "vars": '{"date_cutoff": "2024-01-01", "env": "prod"}'
    }
)
```

--------------------------------

### Example Usage of dbt_mcp_tool Decorator

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/tools.md

An example demonstrating how to use the dbt_mcp_tool decorator to define a dbt tool.

```python
from dbt_mcp.tools.definitions import dbt_mcp_tool
from dbt_mcp.tools.tool_names import ToolName
from pydantic import BaseModel

class ModelDetailsResponse(BaseModel):
    name: str
    description: str
    columns: list[str]

@dbt_mcp_tool(
    title="Get Model Details",
    description="Retrieves detailed information about a dbt model",
    name="get_model_details",
    read_only_hint=True
)
def get_model_details(model_name: str) -> ModelDetailsResponse:
    # Implementation here
    return ModelDetailsResponse(
        name=model_name,
        description="Model description",
        columns=["col1", "col2"]
    )
```

--------------------------------

### Analyze performance trend over last 10 runs

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_performance.md

This example demonstrates how to analyze the performance trend of a dbt model over its last 10 execution runs.

```python
get_model_performance(unique_id="model.analytics.fct_orders", num_runs=10)
```

--------------------------------

### Running Specific Tests Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Python code example for running only tests for a specific dbt model using 'node_selection'.

```python
result = await dbt_mcp.call_tool(
    "test",
    {
        "node_selection": "models/marts/customers"
    }
)
```

--------------------------------

### Anthropic Model Example

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ai_sdk_agent/README.md

Example of configuring the AI SDK to use an Anthropic model.

```typescript
// Anthropic
import { anthropic } from "@ai-sdk/anthropic";
const model = anthropic("claude-sonnet-4-20250514");
```

--------------------------------

### Install AG2 with OpenAI and MCP support

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/ag2_agent/README.md

Installs the AG2 library with necessary dependencies for OpenAI and dbt-mcp.

```bash
pip install "ag2[openai,mcp]>=0.11.0"
```

--------------------------------

### dbt Model Analyzer Tool Usage Examples

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

Example user prompts for the dbt Model Analyzer Tool.

```text
> "Analyze my data modeling approach for best practices"
> "Review the dependencies in my dbt project"
> "Check the data quality patterns in my models"
```

--------------------------------

### generate_staging_model Example Output

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Example SQL output generated by the 'generate_staging_model' tool for a dbt staging model.

```sql
with source as (
    select * from {{ source('raw', 'users') }}
),
renamed as (
    select
        id as user_id,
        email,
        created_at
    from source
)
select * from renamed
```

--------------------------------

### Discovery Queries

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/API_INDEX.md

Examples of using the Discovery Client to fetch models and model lineage.

```python
from dbt_mcp.discovery.client import ModelsFetcher

fetcher = ModelsFetcher(paginator)

# Fetch all models
models = await fetcher.fetch_models(config=config)

# Fetch model lineage
parents = await fetcher.fetch_model_parents(
    model_name="customers",
    config=config
)
```

--------------------------------

### Example usage of query_metrics

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/semantic_layer_client.md

Demonstrates how to use query_metrics to fetch and display query results or errors.

```python
result = await fetcher.query_metrics(
    config,
    metrics=["revenue", "order_count"],
    group_by=["date", "region"],
    where="date >= '2024-01-01'",
    order_by=[OrderByParam(name="date", descending=True)],
    limit=1000
)
if hasattr(result, 'result'):
    print(f"Results:\n{result.result}")
else:
    print(f"Query failed: {result.error}")
```

--------------------------------

### Example 2: Get time-related dimensions for metrics

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/semantic_layer/get_dimensions.md

This example shows how to filter for time-related dimensions for 'total_sales' and 'average_order_value' metrics using the search parameter.

```python
Parameters:
    metrics=["total_sales", "average_order_value"]
    search="time"
```

--------------------------------

### get_environments_for_project

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/admin_api_client.md

Get resolved production and development environments for a project.

```python
async def get_environments_for_project(
    self,
    project_id: int,
    *,
    page_size: int = 100,
) -> tuple[DbtPlatformEnvironment | None, DbtPlatformEnvironment | None]:
    ...
```

--------------------------------

### Discover available packages

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_all_macros.md

This command discovers available packages by calling `get_all_macros` with `return_package_names_only=True`.

```python
get_all_macros(return_package_names_only=True)
```

--------------------------------

### Example usage of get_metrics_compiled_sql

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/semantic_layer_client.md

Demonstrates how to use get_metrics_compiled_sql to retrieve and print compiled SQL or error messages.

```python
result = await fetcher.get_metrics_compiled_sql(
    config,
    metrics=["revenue"],
    group_by=["region"],
    limit=100
)
if hasattr(result, 'sql'):
    print(f"SQL: {result.sql}")
else:
    print(f"Error: {result.error}")
```

--------------------------------

### Semantic Layer Queries

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/API_INDEX.md

Examples of querying the semantic layer, including listing and querying metrics.

```python
from dbt_mcp.semantic_layer.client import SemanticLayerFetcher

fetcher = SemanticLayerFetcher(client_provider)

# List metrics
metrics = await fetcher.list_metrics(config)

# Query metrics
result = await fetcher.query_metrics(
    config,
    metrics=["revenue"],
    group_by=["date"],
    limit=1000
)
```

--------------------------------

### New Users per Week

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/semantic_layer/query_metrics.md

This example demonstrates how to query the number of new users per week for the previous year. It includes steps for identifying metrics, dimensions, and entities, and shows an initial query with a limit for verification, followed by a follow-up query.

```python
metrics=["new_users"]
group_by=[{"name": "metric_time", "grain": "WEEK", "type": "time_dimension"}]
order_by=[{"name": "metric_time", "grain": "WEEK", "descending": false}]
where="{{ TimeDimension('metric_time', 'WEEK') }} >= '2023-01-01' AND {{ TimeDimension('metric_time', 'WEEK') }} < '2024-01-01'"
limit=4
```

```python
metrics=["new_users"]
group_by=[{"name": "metric_time", "grain": "WEEK", "type": "time_dimension"}]
order_by=[{"name": "metric_time", "grain": "WEEK", "descending": false}]
where="{{ TimeDimension('metric_time', 'WEEK') }} >= '2023-01-01' AND {{ TimeDimension('metric_time', 'WEEK') }} < '2024-01-01'"
limit=null
```

--------------------------------

### Get Job Details Request Body

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/admin_api/get_job_details.md

Example JSON payload to specify the job ID for which to retrieve details.

```json
{
  "job_id": 456
}
```

--------------------------------

### Get errors with warnings

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/admin_api/get_job_run_error.md

Example JSON payload to retrieve both error and warning information for a specific job run.

```json
{
  "run_id": 789,
  "include_warnings": true
}
```

--------------------------------

### ElicitingCredentialsProvider.get_credentials Method

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/credentials_and_providers.md

Attempts to get credentials, eliciting missing values interactively if needed.

```python
async def get_credentials(
    self,
) -> tuple[DbtMcpSettings, AdminApiConfig]
```

--------------------------------

### Get performance with test execution history

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_performance.md

This example shows how to retrieve model performance metrics along with the execution history of associated tests.

```python
get_model_performance(unique_id="model.analytics.stg_orders", num_runs=5, include_tests=True)
```

--------------------------------

### Get latest run performance using unique_id

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_performance.md

This example shows the preferred method for retrieving the latest performance metrics of a dbt model by its unique identifier.

```python
get_model_performance(unique_id="model.analytics.stg_orders")
```

--------------------------------

### Manual Testing Configuration (UV)

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/CONTRIBUTING.md

Example configuration file for manual testing with UV, specifying server details and arguments.

```json
{
  "mcpServers": {
    "dbt": {
      "command": "<path-to-uv>",
      "args": [
        "--directory",
        "<path-to-this-directory>/dbt-mcp",
        "run",
        "dbt-mcp",
        "--env-file",
        "<path-to-this-directory>/dbt-mcp/.env"
      ]
    }
  }
}
```

--------------------------------

### Getting lineage with depth control

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/dbt_cli/get_lineage_dev.md

Example of retrieving lineage up to a specified depth.

```python
get_lineage_dev(unique_id="model.my_project.customer_orders", depth=3)
```

--------------------------------

### Fetch a seed by unique_id

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_seed_details.md

Example of fetching a seed using its unique identifier.

```python
get_seed_details(unique_id="seed.analytics.customers")
```

--------------------------------

### Getting full lineage for a model

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/dbt_cli/get_lineage_dev.md

Example of retrieving the complete lineage for a specified model.

```python
get_lineage_dev(unique_id="model.my_project.customer_orders")
```

--------------------------------

### Getting parents using only uniqueId

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_parents.md

Example of how to retrieve parent models by providing only the model's uniqueId.

```python
get_model_parents(uniqueId="model.my_project.customer_orders")
```

--------------------------------

### Getting parents for a model by name

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_parents.md

Example of how to retrieve parent models by providing the model's name.

```python
get_model_parents(name="customer_orders")
```

--------------------------------

### Getting lineage filtered to only models and sources

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/dbt_cli/get_lineage_dev.md

Example of retrieving lineage, including only 'Model' and 'Source' resource types.

```python
get_lineage_dev(unique_id="model.my_project.customer_orders", types=["Model", "Source"])
```

--------------------------------

### Getting lineage excluding tests

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/dbt_cli/get_lineage_dev.md

Example of retrieving lineage, excluding 'Test' resource types by specifying allowed types.

```python
get_lineage_dev(unique_id="model.my_project.customer_orders", types=["Model", "Source", "Seed", "Snapshot", "Exposure"])
```

--------------------------------

### fetch_project_environment_responses

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/admin_api_client.md

Fetch all environments for a project using pagination.

```python
async def fetch_project_environment_responses(
    self,
    project_id: int,
    *,
    page_size: int = 100,
) -> list[DbtPlatformEnvironmentResponse]:
    ...
```

--------------------------------

### Fetch a test when only the node name is known

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_test_details.md

This example demonstrates fetching a dbt test when only the node's name is available.

```python
get_test_details(name="is_empty_string")
```

--------------------------------

### Making Tool Calls Programmatically

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/README.md

Shows how to initialize the dbt-mcp server, list available tools, and make a tool call.

```python
from dbt_mcp.mcp.server import create_dbt_mcp
from dbt_mcp.config.config import load_config
import asyncio

async def call_tool():
    config = load_config()
    server = await create_dbt_mcp(config)
    
    # List available tools
    tools = await server.list_tools()
    for tool in tools:
        print(f"{tool.name}: {tool.description}")
    
    # Call a tool
    result = await server.call_tool(
        "get_all_models",
        {}
    )
    print(result)

asyncio.run(call_tool())
```

--------------------------------

### Fetch a seed when only the node name is known

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_seed_details.md

Example of fetching a seed using its node name when the unique ID is not available.

```python
get_seed_details(name="customers")
```

--------------------------------

### Getting parents for a model by uniqueId (more precise)

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_parents.md

Example of how to retrieve parent models by providing both the model's name and its uniqueId for a more precise match.

```python
get_model_parents(name="customer_orders", uniqueId="model.my_project.customer_orders")
```

--------------------------------

### Fetch a semantic model by unique_id

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_semantic_model_details.md

This example shows how to retrieve semantic model details using its unique identifier.

```python
get_semantic_model_details(unique_id="semantic_model.analytics.customers")
```

--------------------------------

### Tool Definition Pattern

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/API_INDEX.md

Shows how tools are defined using decorators and context injection, with parameters for title and description.

```python
@dbt_mcp_tool(title="...", description="...")
def my_tool(param: str) -> ResponseType:
    return result
```

--------------------------------

### Fetch a semantic model when only the node name is known

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_semantic_model_details.md

This example demonstrates fetching semantic model details when only the node name is available.

```python
get_semantic_model_details(name="customers")
```

--------------------------------

### SourcesFetcher Constructor

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/discovery_client.md

Initializes a SourcesFetcher with a PaginatedResourceFetcher instance.

```python
class SourcesFetcher:
    def __init__(self, paginator: PaginatedResourceFetcher)
```

--------------------------------

### Average Order Value by Product Category

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/semantic_layer/query_metrics.md

This example shows how to query the average order value, grouped by product category, with a filter for orders over $100. It includes an initial query with a limit for verification, followed by a follow-up query with the limit removed.

```python
metrics=["average_order_value"]
group_by=[{"name": "product_category", "type": "dimension"}]
where="{{ Dimension('order_value') }} > 100"
limit=10
```

```python
metrics=["average_order_value"]
group_by=[{"name": "product_category", "type": "dimension"}]
where="{{ Dimension('order_value') }} > 100"
limit=null
```

--------------------------------

### Fallback method using only name

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_model_performance.md

This example illustrates the fallback method for retrieving model performance metrics using only the model's name, which should only be used when the unique_id is unknown.

```python
get_model_performance(name="stg_orders", num_runs=5)
```

--------------------------------

### get_token method

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/credentials_and_providers.md

Returns the current authentication token.

```python
def get_token(self) -> str
```

--------------------------------

### ConfigProvider.get_config Method

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/credentials_and_providers.md

Retrieves the configuration object.

```python
async def get_config(self) -> ConfigType
```

--------------------------------

### Manual Testing Configuration (Oauth)

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/CONTRIBUTING.md

Example configuration file for manual testing with Oauth, including environment variables for dbt host.

```json
{
  "mcpServers": {
    "dbt": {
      "command": "<path-to-uv>",
      "args": [
        "--directory",
        "<path-to-this-directory>/dbt-mcp",
        "run",
        "dbt-mcp"
      ],
      "env": {
        "DBT_HOST": "<dbt-host-with-custom-subdomain>"
      }
    }
  }
}
```

--------------------------------

### Adding a tool with interactive UI

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/CONTRIBUTING.md

Example of defining a tool that has an associated interactive UI, using structured_output and meta to link to a UI resource.

```python
    @dbt_mcp_tool(
        description=get_prompt("category/tool_name"),
        title="My Visualization",
        read_only_hint=True,
        structured_output=True,
        meta={"ui": {"resourceUri": "ui://dbt-mcp/my-app"}},
    )
    async def my_viz_tool(context: MyToolContext, param: str) -> MyResult:
        ...
```

--------------------------------

### Get Lineage (Dev)

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Get lineage from local manifest.json with filtering.

```python
@dbt_mcp_tool(
    title="Get Lineage (Dev)",
    description="Get lineage from local manifest.json with filtering"
)
def get_lineage_dev(
    resource_name: str | None = None,
    unique_id: str | None = None,
    types: list[LineageResourceType] | None = None,
    depth: int | None = None,
    direction: str = "both",
) -> dict
```

--------------------------------

### PaginatedResourceFetcher Constructor

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/discovery_client.md

Initializes a PaginatedResourceFetcher with paths for edges and page info, and optional pagination limits.

```python
class PaginatedResourceFetcher:
    def __init__(
        self,
        edges_path: tuple[str, ...],
        page_info_path: tuple[str, ...],
        page_size: int = DEFAULT_PAGE_SIZE,
        max_node_query_limit: int = DEFAULT_MAX_NODE_QUERY_LIMIT,
    )
```

--------------------------------

### Get Job Run Details

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/admin_api_client.md

Returns full run details with execution information, steps, and artifacts metadata.

```python
async def get_job_run_details(
    self, account_id: int, run_id: int
) -> dict[str, Any]:
    # ... implementation details ...
    pass
```

--------------------------------

### Customer Satisfaction Proxy (NPS) by Region

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/semantic_layer/query_metrics.md

This example addresses a user's request for customer satisfaction. Since a direct metric is not available, it suggests using Net Promoter Score (NPS) as a proxy and provides the parameters for querying NPS by region.

```python
metrics=["net_promoter_score"]
group_by=[{"name": "region", "type": "dimension"}]
order_by=[{"name": "net_promoter_score", "descending": true}]
limit=10
```

--------------------------------

### Get Node Details (Dev)

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Get node details from local manifest.json.

```python
@dbt_mcp_tool(
    title="Get Node Details (Dev)",
    description="Get node details from local manifest.json"
)
def get_node_details_dev(
    unique_id: str,
) -> dict
```

--------------------------------

### Registering an MCP resource for an interactive UI

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/CONTRIBUTING.md

Example of registering an MCP resource at a specific UI URI to serve an HTML app.

```python
@dbt_mcp.resource(
    uri="ui://dbt-mcp/my-app",
    name="My App",
    mime_type="text/html;profile=mcp-app",
)
def get_my_app_ui() -> str:
    return Path("packages/my-app/dist/index.html").read_text()
```

--------------------------------

### generate_model_yaml Example Output

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Example YAML output generated by the 'generate_model_yaml' tool for dbt models.

```yaml
version: 2
models:
  - name: customers
    description: "Customer dimension with aggregated metrics"
    columns:
      - name: customer_id
        description: "Primary key"
        tests:
          - unique
          - not_null
      - name: first_name
      - name: email
```

--------------------------------

### generate_source Example Output

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/_autodocs/api-reference/cli_and_codegen.md

Example YAML output generated by the 'generate_source' tool for dbt sources.

```yaml
version: 2
sources:
  - name: raw
    tables:
      - name: users
        columns:
          - name: id
          - name: email
          - name: created_at
```

--------------------------------

### Get macros for specific packages

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/src/dbt_mcp/prompts/discovery/get_all_macros.md

This command retrieves macros for specific packages by calling `get_all_macros` with a list of package names.

```python
get_all_macros(package_names=['my_project'])
```

--------------------------------

### Create a virtual environment

Source: https://github.com/dbt-labs/dbt-mcp/blob/main/examples/aws_strands_agent/README.md

Commands to create and activate a Python virtual environment.

```bash
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
```