obsidian_list_files_in_dir

Explore and list files and directories within your Obsidian vault to navigate organized sections like Zettelkasten folders.

Instructions

List files and directories in a specific vault directory.

Use this tool to explore the contents of a specific folder, such as your
Zettelkasten directory or any other organized section of your vault.

Args:
    params (ListFilesInput): Contains:
        - dirpath (str): Relative path to directory (empty for root)

Returns:
    str: Formatted list of directories and files in the specified path
    
Example:
    For dirpath="Zettelkasten", lists all notes in your Zettelkasten folder.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Implementation Reference

src/custom_obsidian_mcp/server.py:442-470 (handler)

Handler function that executes the tool: constructs API endpoint, calls ObsidianClient.get(), extracts files/directories, formats output using helper, handles errors.

async def list_files_in_dir(params: ListFilesInput) -> str:
    """List files and directories in a specific vault directory.
    
    Use this tool to explore the contents of a specific folder, such as your
    Zettelkasten directory or any other organized section of your vault.
    
    Args:
        params (ListFilesInput): Contains:
            - dirpath (str): Relative path to directory (empty for root)
    
    Returns:
        str: Formatted list of directories and files in the specified path
        
    Example:
        For dirpath="Zettelkasten", lists all notes in your Zettelkasten folder.
    """
    try:
        endpoint = f"/vault/{params.dirpath}" if params.dirpath else "/vault/"
        result = await obsidian_client.get(endpoint)
        files = result.get("files", [])
        directories = result.get("directories", [])
        
        return format_file_list(files, directories)
        
    except ObsidianAPIError as e:
        return json.dumps({
            "error": str(e),
            "success": False
        }, indent=2)

src/custom_obsidian_mcp/server.py:48-56 (schema)

Pydantic model defining input schema: optional dirpath (str, default empty for root).

class ListFilesInput(BaseModel):
    """Input for listing files in a directory."""
    model_config = ConfigDict(str_strip_whitespace=True, extra='forbid')
    
    dirpath: Optional[str] = Field(
        default="",
        description="Relative directory path to list (empty string for vault root)",
        max_length=500
    )

src/custom_obsidian_mcp/server.py:432-441 (registration)

MCP tool registration decorator specifying name and annotations (read-only, idempotent).

@mcp.tool(
    name="obsidian_list_files_in_dir",
    annotations={
        "title": "List Files in Directory",
        "readOnlyHint": True,
        "destructiveHint": False,
        "idempotentHint": True,
        "openWorldHint": False
    }
)

src/custom_obsidian_mcp/server.py:311-326 (helper)

Helper function formats lists of files and directories into markdown with emojis and sections.

def format_file_list(files: List[str], directories: List[str]) -> str:
    """Format file and directory lists for display."""
    result = []
    
    if directories:
        result.append("## Directories")
        for d in sorted(directories):
            result.append(f"- 📁 {d}/")
        result.append("")
    
    if files:
        result.append("## Files")
        for f in sorted(files):
            result.append(f"- 📄 {f}")
    
    return "\n".join(result) if result else "No files or directories found."

Obsidian MCP Server