dbt_ls
Discover and list dbt project resources like models, tests, and sources using JSON or text outputs to understand project structure, identify dependencies, and select resources for operations such as running or testing.
Instructions
List dbt resources. An AI agent should use this tool when it needs to discover available models, tests, sources, and other resources within a dbt project. This helps the agent understand the project structure, identify dependencies, and select specific resources for other operations like running or testing.
Returns:
When output_format is 'json' (default):
- With verbose=False (default): returns a simplified JSON with only name, resource_type, and depends_on.nodes
- With verbose=True: returns a full JSON with all resource details
When output_format is 'name', 'path', or 'selector', returns plain text with the respective format.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| exclude | No | Models to exclude | |
| models | No | Specific models to list, using the dbt selection syntax. Note that you probably want to specify your selection here e.g. silver.fact | |
| output_format | No | Output format (json, name, path, or selector) | json |
| profiles_dir | No | Directory containing the profiles.yml file (defaults to project_dir if not specified) | |
| project_dir | No | ABSOLUTE PATH to the directory containing the dbt project (e.g. '/Users/username/projects/dbt_project' not '.') | . |
| resource_type | No | Type of resource to list (model, test, source, etc.) | |
| selector | No | Named selector to use | |
| verbose | No | Return full JSON output instead of simplified version |
Implementation Reference
- src/tools.py:134-210 (handler)Main execution logic for the dbt_ls MCP tool. Constructs dbt ls command from parameters, executes via execute_dbt_command, formats output using ls_formatter, and processes the result.@mcp.tool() async def dbt_ls( models: Optional[str] = Field( default=None, description="Specific models to list, using the dbt selection syntax. Note that you probably want to specify your selection here e.g. silver.fact" ), selector: Optional[str] = Field( default=None, description="Named selector to use" ), exclude: Optional[str] = Field( default=None, description="Models to exclude" ), resource_type: Optional[str] = Field( default=None, description="Type of resource to list (model, test, source, etc.)" ), project_dir: str = Field( default=".", description="ABSOLUTE PATH to the directory containing the dbt project (e.g. '/Users/username/projects/dbt_project' not '.')" ), profiles_dir: Optional[str] = Field( default=None, description="Directory containing the profiles.yml file (defaults to project_dir if not specified)" ), output_format: str = Field( default="json", description="Output format (json, name, path, or selector)" ), verbose: bool = Field( default=False, description="Return full JSON output instead of simplified version" ) ) -> str: """List dbt resources. An AI agent should use this tool when it needs to discover available models, tests, sources, and other resources within a dbt project. This helps the agent understand the project structure, identify dependencies, and select specific resources for other operations like running or testing. Returns: When output_format is 'json' (default): - With verbose=False (default): returns a simplified JSON with only name, resource_type, and depends_on.nodes - With verbose=True: returns a full JSON with all resource details When output_format is 'name', 'path', or 'selector', returns plain text with the respective format. """ # Log diagnostic information logger.info(f"Starting dbt_ls with project_dir={project_dir}, output_format={output_format}") command = ["ls"] if models: command.extend(["-s", models]) if selector: command.extend(["--selector", selector]) if exclude: command.extend(["--exclude", exclude]) if resource_type: command.extend(["--resource-type", resource_type]) command.extend(["--output", output_format]) command.extend(["--quiet"]) logger.info(f"Executing dbt command: dbt {' '.join(command)}") result = await execute_dbt_command(command, project_dir, profiles_dir) logger.info(f"dbt command result: success={result['success']}, returncode={result.get('returncode')}") # Use the centralized result processor with ls_formatter formatter = partial(ls_formatter, output_format=output_format, verbose=verbose) return await process_command_result( result, command_name="ls", output_formatter=formatter, include_debug_info=True # Include extra debug info for this command )
- src/tools.py:135-168 (schema)Pydantic Field definitions providing input schema, types, defaults, and descriptions for the MCP tool parameters.async def dbt_ls( models: Optional[str] = Field( default=None, description="Specific models to list, using the dbt selection syntax. Note that you probably want to specify your selection here e.g. silver.fact" ), selector: Optional[str] = Field( default=None, description="Named selector to use" ), exclude: Optional[str] = Field( default=None, description="Models to exclude" ), resource_type: Optional[str] = Field( default=None, description="Type of resource to list (model, test, source, etc.)" ), project_dir: str = Field( default=".", description="ABSOLUTE PATH to the directory containing the dbt project (e.g. '/Users/username/projects/dbt_project' not '.')" ), profiles_dir: Optional[str] = Field( default=None, description="Directory containing the profiles.yml file (defaults to project_dir if not specified)" ), output_format: str = Field( default="json", description="Output format (json, name, path, or selector)" ), verbose: bool = Field( default=False, description="Return full JSON output instead of simplified version" ) ) -> str:
- src/server.py:86-89 (registration)Registers all MCP tools, including dbt_ls, by calling register_tools(mcp) where the tool functions are defined and decorated.mcp = FastMCP("dbt-cli", log_level="ERROR") # Register tools register_tools(mcp)
- src/tools.py:25-25 (helper)The register_tools function that defines (as nested functions) and registers all MCP tools including dbt_ls via @mcp.tool() decorators.def register_tools(mcp: FastMCP) -> None: