How to Control Directory Listing Depth in Desktop Commander MCP

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.

How the Depth Parameter Works

The listDirectory function signature in src/tools/filesystem.ts defines depth as an optional parameter with a default value:

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).

Practical Examples

List Only Top-Level Directory (No Recursion)

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

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:

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:

// 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.

Key Implementation Details

The depth-limiting logic resides in three interconnected parts of 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)
• 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}