# How to Control Directory Listing Depth in Desktop Commander MCP

> Control directory listing depth in Desktop Commander MCP using the listDirectory function's depth parameter. Customize nested directory display levels easily.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: how-to-guide
- Published: 2026-08-02

---

**The `listDirectory` function in Desktop Commander MCP accepts a `depth` parameter that defaults to `2` levels, and you can override it to control how many nested directory levels are displayed.**

Desktop Commander MCP is an open-source Model Context Protocol (MCP) server that provides filesystem access to AI assistants. Controlling directory listing depth is essential when working with deep project structures or when you want to limit output size. The depth-control mechanism is implemented in the `listDirectory` utility in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts).

## How the Depth Parameter Works

The `listDirectory` function signature in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts) defines `depth` as an optional parameter with a default value:

```typescript
export async function listDirectory(
    dirPath: string,
    depth: number = 2               // ← default recursion depth
): Promise<string[]> { … }

```

The `depth` argument specifies the **maximum recursion level** — essentially how many subdirectory levels the function will explore. The implementation respects this value through its internal `listRecursive` helper, which stops recursion when `currentDepth <= 0`.

### Default Behavior

If you omit the `depth` argument, the function uses the built-in default of **2**, which returns:
- The top-level folder contents
- One level of child directories

This default is also used when the file-read fallback detects a directory path (see the call at lines 456–462 in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts)).

## Practical Examples

### List Only Top-Level Directory (No Recursion)

To disable recursion entirely and show only immediate directory contents, set `depth` to `1`:

```typescript
import { listDirectory } from './src/tools/filesystem.js';

const topOnly = await listDirectory('/Users/alice/projects', 1);
console.log(topOnly);   // shows only entries directly under /projects

```

### Deep Dive: Three Nested Levels

For deeper exploration of project structures, increase the depth value:

```typescript
const deep = await listDirectory('/Users/alice/projects', 3);
deep.forEach(line => console.log(line));

```

This returns entries from the target directory plus up to two levels of nested subdirectories.

## Using Depth Control via Remote MCP Tools

When invoking Desktop Commander MCP through a client, pass the `depth` parameter in the tool arguments:

```typescript
// Assume `tool` is the MCP tool runner
const result = await tool.run('list_directory', {
  path: '/Users/alice/projects',
  depth: 4          // request a deeper tree
});
console.log(result);

```

The server passes this value directly to the internal `listDirectory` function in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts).

## Key Implementation Details

The depth-limiting logic resides in three interconnected parts of [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts):

| Location | Purpose |
|----------|---------|
| **Lines 720–744** | `listDirectory` function definition with `depth` parameter and default value |
| **Lines 456–462** | Fallback call from `readFileFromDisk` when a directory path is provided, using default depth |
| **Lines 726–785** | `listRecursive` helper that decrements depth and stops when `currentDepth <= 0` |

The recursive implementation ensures that each nested call receives `depth - 1`, guaranteeing the limit is enforced regardless of directory structure complexity.

## Summary

- **Primary mechanism**: The `depth` parameter in `listDirectory` ([`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts))
- **Default value**: `2` (top level plus one subdirectory level)
- **Minimum value**: `1` (no recursion, top-level only)
- **Behavior**: Recursion stops when depth counter reaches zero
- **Remote access**: Pass `depth` in tool arguments when using MCP clients

## Frequently Asked Questions

### What is the maximum depth I can specify?

There is no enforced maximum in the Desktop Commander MCP source code. You can specify any positive integer, though practical limits depend on your system's stack depth and the complexity of the directory structure being traversed.

### Why does the default depth stop at 2 levels?

The default of `2` balances information density with performance. According to the implementation in [`src/tools/filesystem.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/tools/filesystem.ts), this provides immediate context (the target directory) plus a preview of its subdirectories without overwhelming output on large projects.

### How do I check what depth was used for a listing?

The `listDirectory` function does not return metadata about the depth used. If you need to verify behavior, check your call site — whether you're calling `listDirectory` directly or invoking the remote tool with an explicit `depth` argument.

### Does depth control affect file contents or just directory entries?

The `depth` parameter controls **directory traversal only**. File contents are never read during `listDirectory` operations regardless of depth. The function returns path strings and entry information, not file data.