Desktop Commander MCP

https://github.com/wonderwhy-er/desktopcommandermcp
Admin
Desktop Commander MCP is a Model Context Protocol server that enables AI assistants to execute...
Tokens:148,909
Snippets:1,166
Trust Score:9
License:MIT
Update:3 weeks ago
Show doc for...
Tokens:
Raw
### Local installation from GitHub

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/FAQ.md

Clone the repository and run the setup script for a local installation.

```bash
git clone https://github.com/wonderwhy-er/ClaudeComputerCommander.git
cd ClaudeComputerCommander
npm run setup
```

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

### Start Remote Device with global install

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Shorter equivalent command when Desktop Commander is installed globally.

```bash
desktop-commander remote
```

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

### Install via local checkout

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Install Desktop Commander by cloning the repository and running the setup command. The setup installs dependencies, builds the server, and configures Claude's desktop app. Manual updates required; uninstall via npx remove or removing the cloned directory and MCP entry.

```bash
git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm run setup
```

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

### Direct installation

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/FAQ.md

Run the setup command directly via npx to install Claude Desktop Commander.

```bash
npx @wonderwhy-er/desktop-commander setup
```

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

### Clone, build, and run Remote Device with debug logging

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Use these commands to set up the repository and start the Remote Device with debug logging enabled. Requires Node.js and npm installed. Run from the repository root after cloning.

```bash
git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP
npm install
npm run build
node dist/index.js remote --debug
```

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

### Install and first run: npm install, onboard, dashboard

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/skills/ai-tools-setup/references/openclaw.md

Install OpenClaw globally, run guided onboarding with the background service, and open the browser Control UI. The Control UI default is http://127.0.0.1:18789/; if that port doesn't load, check onboarding output or run `openclaw doctor` for the actual port.

```bash
npm install -g openclaw@latest
```

```bash
openclaw onboard --install-daemon
```

```bash
openclaw dashboard
```

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

### Install and first run: npm install, openclaw onboard --install-daemon, openclaw dashboard

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/claude/skills/ai-tools-setup/references/openclaw.md

Install OpenClaw globally, run guided onboarding with daemon installation, and open the browser Control UI. Requires Node 24 (or 22.19+) and a model provider API key.

```bash
# Install
npm install -g openclaw@latest

# Guided onboarding + install the background service
openclaw onboard --install-daemon

# Open the browser Control UI
openclaw dashboard
```

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

### async start()

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/remote-device.md

Starts the remote device: initializes the desktop integration, fetches Supabase config, restores the persisted session, authenticates if needed, registers the device, opens the realtime channel, and supervises recovery loops.

```APIDOC
## Method: `async start()`

### Description
Starts the remote device, connecting it to hosted Remote MCP service and beginning relay of tool calls to the local server.

### Behavior
- Initializes the desktop integration.
- Fetches Supabase configuration from the server.
- Restores a persisted device session from `~/.desktop-commander-device/device.json` (up to 3 retries at 250 ms).
- Authenticates with `DeviceAuthenticator.authenticate` when needed.
- Registers the device and opens the realtime channel.
- Supervises recovery loops (readiness checks, reconnect with backoff, heartbeat).
- Spawns `node dist/index.js` with env including `DC_REMOTE_DEVICE=true` for remote-side redirection.

### Returns
- **Promise<void>** - Resolves when the device has started successfully.

```

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

### Run Hermes setup with Nous Portal (hermes setup --portal)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/claude/skills/ai-tools-setup/references/hermes.md

Run the smoothest first-run setup: one OAuth via Nous Portal covers a model plus the four Tool Gateway tools (web search, image generation, TTS, browser). Re-run this command if a Portal login code is rejected.

```bash
hermes setup --portal
```

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

### Start normally and with --debug

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Starts the Remote Device normally, or with verbose diagnostics using `--debug`.

```bash
# Start normally
npx @wonderwhy-er/desktop-commander@latest remote

# Start with verbose diagnostics
npx @wonderwhy-er/desktop-commander@latest remote --debug
```

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

### Start with --debug for diagnostics

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Starts the Remote Device with verbose logging to help diagnose connectivity issues.

```bash
npx @wonderwhy-er/desktop-commander@latest remote --debug
```

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

### MCPDevice usage

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/remote-device.md

Usage example for MCPDevice: creates a device with session persistence and starts it. The start() method blocks until SIGINT/SIGTERM triggers graceful shutdown.

```ts
import { MCPDevice } from './src/remote-device/device.js';

const device = new MCPDevice({ persistSession: true });
await device.start();   // blocks; SIGINT/SIGTERM trigger graceful shutdown
```

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

### MCPDevice start method signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/remote-device.md

Signature for the start method. Initializes the desktop integration, fetches Supabase config, restores a persisted session, authenticates when needed, registers the device, and supervises recovery loops.

```ts
async start()
```

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

### Usage example for FilteredStdioServerTransport

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/custom-stdio.md

Usage example showing instantiation at process start, storing on global.mcpTransport, and calling enableNotifications, sendLog, sendProgress, and sendCustomNotification after the MCP handshake.

```ts
import { FilteredStdioServerTransport } from './src/custom-stdio.js';

const transport = new FilteredStdioServerTransport();
global.mcpTransport = transport;   // consumed by utils/logger.ts

// after MCP handshake:
transport.enableNotifications();
transport.sendLog('info', 'Hello from the server', { extra: 1 });
transport.sendProgress('token-1', 5, 10);
transport.sendCustomNotification('my/event', { foo: 'bar' });
```

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

### Install via npx setup command

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Install Desktop Commander for Claude Desktop via npx. The --debug flag enables Node.js inspector debugging. Auto-updates on restart; manual update by re-running setup; uninstall with the remove command.

```bash
npx @wonderwhy-er/desktop-commander@latest setup
```

```bash
npx @wonderwhy-er/desktop-commander@latest setup --debug
```

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

### Start with --no-persist-session and --logout

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Starts without saving or reusing the session, or removes saved local credentials with `--logout`.

```bash
# Start without saving/reusing the session
npx @wonderwhy-er/desktop-commander@latest remote --no-persist-session

# Remove saved local credentials
npx @wonderwhy-er/desktop-commander@latest remote --logout
```

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

### Install via Docker (macOS/Linux and Windows)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Install Desktop Commander in Docker on macOS/Linux (bash) or Windows PowerShell. Requires Docker Desktop installed and running. The installer checks Docker, pulls the image, prompts for folder mounting, and configures Claude Desktop. Persistent work environment survives restarts.

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)
```

```powershell
iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.ps1'))
```

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

### MCP server entry example

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/claude/skills/ai-tools-setup/references/claude-desktop-mcp.md

Example stdio MCP server entry with launch command, args, and optional env. On Windows, npx may need to be wrapped as cmd /c npx ...; use absolute paths for local scripts and keep secrets in env.

```json
{
  "mcpServers": {
    "example": {
      "command": "npx",
      "args": ["-y", "@scope/some-mcp-server"],
      "env": { "SOME_API_KEY": "..." }
    }
  }
}
```

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

### start_process

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/endpoints.md

Starts a new process. Returns PID and shell. `node:local` starts a virtual negative-PID session. Blocked commands return an error.

```APIDOC
## start_process

### Description
Starts a new process. Returns PID and shell. `node:local` starts a virtual negative-PID session. Blocked commands return an error.

### Method
MCP Tool Call

### Endpoint
`start_process`

### Parameters
#### Request Body
- **command** (string) - Required - Command to execute.
- **shell** (string) - Optional - Shell to use.
- **cwd** (string) - Optional - Working directory.
- **env** (object) - Optional - Environment variables.

### Response
#### Success Response
- **message** (string) - `Process started with PID <pid> (shell: <shell>)`.
- **state** (object) - Process state and timing.

#### Response Example
```json
{
  "message": "Process started with PID 123 (shell: bash)"
}
```
```

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

### initialize

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/endpoints.md

MCP initialize method for session setup and protocol negotiation.

```APIDOC
## initialize

### Description
Initializes the MCP session, negotiates protocol version, and stores client information. Also runs welcome-onboarding eligibility checks.

### Method
initialize

### Request
- **protocolVersion** (string) - Required - The protocol version requested by the client.
- **capabilities** (object) - Required - Client capabilities.
- **clientInfo** (object) - Required - Information about the client.

### Response
- **protocolVersion** (string) - The negotiated protocol version.
- **capabilities** (object) - Server capabilities including tools, resources, prompts, and logging.
- **serverInfo** (object) - Server information with name "desktop-commander" and version.

### Notes
- Stores clientInfo and runs welcome-onboarding eligibility.
- Negotiates protocol version: requests in SUPPORTED_PROTOCOL_VERSIONS are echoed, otherwise LATEST_PROTOCOL_VERSION is used.
```

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

### Install Hermes Agent CLI (curl for Unix, iex for Windows)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/claude/skills/ai-tools-setup/references/hermes.md

Install the Hermes Agent CLI on Linux/macOS/WSL2/Android (Termux) via curl, or on Windows native PowerShell via iex. The installer sets up the CLI and desktop app; see the Installation Guide for per-user vs. root layout and Windows notes.

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```

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

### Development Command Example

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Example of a natural language command for development. Claude runs an interactive Node.js session to test the API.

```text
"Start Node.js and test this API" → Claude runs interactive Node session
```

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

### Usage examples for tools/list and resources/read

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/ui-resources.md

Shows how hosts consume the resources over MCP: tools/list includes _meta with resource URI and optional widgetAccessible, and resources/read returns inlined HTML.

```json
// tools/list for read_file includes (A/B-permitting):
{ "_meta": { "ui/resourceUri": "ui://desktop-commander/file-preview", "openai/widgetAccessible": true } }

// resources/read
{ "uri": "ui://desktop-commander/config-editor" }
// -> contents[0].text = "<inlined HTML>"
```

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

### Update local checkout with git pull and npm run setup

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Updates a local checkout of Desktop Commander by pulling the latest changes and running the setup script.

```bash
cd DesktopCommanderMCP && git pull && npm run setup
```

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

### SearchManager usage example

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/search-manager.md

Example usage of the SearchManager: starts a content search for 'TODO' with case-insensitive matching and context lines, then polls for results until complete, logging each match, and finally terminates the session.

```ts
import { searchManager } from './src/search-manager.js';

const { sessionId, isComplete, results } = await searchManager.startSearch({
  rootPath: '/workspace/home',
  pattern: 'TODO',
  searchType: 'content',
  ignoreCase: true,
  contextLines: 3,
});

let page = searchManager.readSearchResults(sessionId, 0, 100);
while (!page.isComplete || page.hasMoreResults) {
  if (page.results.length) console.log(page.results.map(r => `${r.file}:${r.line} ${r.match}`));
  await new Promise(r => setTimeout(r, 100));
  page = searchManager.readSearchResults(sessionId, 0, 100);
}
searchManager.terminateSearch(sessionId);
```

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

### Log Hello World to console

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/test/samples/01_sample_simple.pdf

Logs the string 'Hello World' to the console. This is a minimal example of JavaScript syntax.

```javascript
console.log('Hello World');
```

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

### startProcess

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/process-tools.md

Starts a new process with the given command and optional timeout.

```APIDOC
## startProcess

### Description
Starts a new process with the given command and optional timeout.

### Parameters
- **command** (string) - Required - The command to execute.
- **timeout_ms** (number) - Optional - Timeout in milliseconds.

### Returns
- **ServerResult** - On success, `content[0].text` contains "Process started with PID ...". On failure, `isError` is `true`.

### Example
```ts
const started = await startProcess({ command: 'python3 -i', timeout_ms: 10000 });
```
```

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

### startProcess

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/process-tools.md

Documentation for the startProcess function, which starts a new process in an interactive session.

```APIDOC
## startProcess

### Description
Starts a new process in an interactive session. It parses the provided arguments, validates the command against a blocklist, resolves the shell, and delegates execution to the terminal manager. It also supports a special `node:local` command that runs code in a fresh Node.js temporary script.

### Method
Function call

### Signature
`startProcess(args: unknown): Promise<ServerResult>`

### Parameters
- **args** (unknown) - Required - The arguments object. Must conform to `StartProcessArgsSchema`.

#### Request Body Fields
- **command** (string) - Required - The command to execute.
- **timeout_ms** (number) - Required - Timeout in milliseconds.
- **shell** (string) - Optional - The shell to use. If not provided, the default shell is used.
- **verbose_timing** (boolean) - Optional - Whether to include timing information.
- **origin** ('ui' | 'llm') - Optional - The origin of the request.

### Behavior
- **Blocklist** - Rejects with `Error: Command not allowed: <command>` when `commandManager.validateCommand` fails.
- **`node:local`** - A literal `node:local` command starts a virtual session (negative PID from a counter starting at -1000). Each `interact_with_process` call runs the sent code as a fresh Node.js `.mjs` temp script (default timeout 30000 ms; state is not preserved between calls).
- **Shell resolution** - Uses `args.shell`, else `config.defaultShell`, else `$COMSPEC`/`$SHELL`, else `cmd.exe`/`/bin/sh`.
- Delegates to `terminalManager.executeCommand`, then classifies output state with `analyzeProcessState` and appends status/timing messages.

### Returns
Returns text content `Process started with PID <pid> (shell: <shell>)...` and `isError: true` with `Error: ...` when invalid, blocked, or spawn-failed (`pid === -1` - in that case `result.output` is the message, and errors are reported as `{ content, isError: true }`).
```

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

### ConfigManager.init()

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/config-manager.md

Initializes the ConfigManager by loading the configuration from disk, creating it if missing, migrating legacy configs, and starting the file watcher.

```APIDOC
## ConfigManager.init()

### Description
Loads config from disk, creating it with `getDefaultConfig()` when missing, migrates legacy configs, stamps the version, and starts the config file watcher. Never throws: on any failure it falls back to the default config and continues.

### Method
init

### Signature
`async init()`

### Parameters
None

### Returns
`Promise<void>`

### Example
```ts
await configManager.init();
```
```

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

### Search/Replace Example for src/main.js

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Concrete example of the search/replace block format. It replaces the old console.log message with a new one in src/main.js.

```text
src/main.js
<<<<<<< SEARCH
console.log("old message");
=======
console.log("new message");
>>>>>>> REPLACE
```

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

### PDF Tool Usage Examples

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/pdf-tools.md

Examples for parsing PDFs to markdown, converting markdown to PDF, editing PDF structures, and extracting images.

```ts
import { parsePdfToMarkdown, parseMarkdownToPdf, editPdf, extractImagesFromPdf } from './src/tools/pdf/index.js';

const parsed = await parsePdfToMarkdown('report.pdf', [1, 2]);        // page 1–2 (1-based)
console.log(parsed.metadata.title, parsed.pages[0].text);

const buffer = await parseMarkdownToPdf('# Title

Hello', { margin: 20 });

const modified = await editPdf('dump.pdf', [
  { type: 'delete', pageIndexes: [0, 2] },
  { type: 'insert', pageIndex: 1, markdown: '# New Page' },
]);

const imgs = await extractImagesFromPdf(new Uint8Array(buffer), undefined, { format: 'jpeg', quality: 80 });
```

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

### Install via Smithery

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/FAQ.md

Install Claude Desktop Commander using the Smithery CLI. Requires Node.js 18+ and a Claude Pro subscription.

```bash
npx -y @smithery/cli install @wonderwhy-er/desktop-commander --client claude
```

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

### Install Hermes CLI on Windows (PowerShell)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/skills/ai-tools-setup/references/hermes.md

Installs the Hermes CLI natively on Windows using PowerShell's Invoke-Expression with the remote install script.

```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```

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

### init() method signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/config-manager.md

Initializes the config manager by loading the config from disk, creating it with defaults if missing, migrating legacy fields, stamping the version, and starting the file watcher. Never throws; falls back to defaults on failure.

```typescript
async init()
```

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

### Disable onboarding with --no-onboarding flag

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Disables onboarding prompts for the session. Use the --no-onboarding flag with node, npm run start:no-onboarding, or add it to the claude_desktop_config.json args for npx installations. Onboarding is also automatically disabled when the MCP client name is 'desktop-commander' or after 10+ tool calls.

```bash
# Disable onboarding for this session
node dist/index.js --no-onboarding

# Or if using npm scripts
npm run start:no-onboarding

# For npx installations, modify your claude_desktop_config.json:
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": [
        "-y",
        "@wonderwhy-er/desktop-commander@latest",
        "--no-onboarding"
      ]
    }
  }
}
```

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

### Install via bash script (macOS)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Install Desktop Commander on macOS using the bash script installer. The script handles dependencies and configuration automatically. Auto-updates; manual update by re-running the command; uninstall via npx remove.

```bash
curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install.sh | bash
```

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

### Remote Access Command Example

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Example of a natural language command for remote access. Claude maintains an SSH session to execute the command.

```text
"SSH to my server and check disk space" → Claude maintains SSH session
```

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

### Run Remote Device source directly

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Starts the Remote Device directly from source without building. Useful for quick testing during development.

```bash
npm run device:start
```

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

### Start Remote Device for Desktop Commander

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Starts the Remote Device for using Desktop Commander from ChatGPT, Claude web, and other AI services. On first run, complete browser authentication, then connect your AI at mcp.desktopcommander.app. Stop the local device temporarily with Ctrl+C.

```bash
npx @wonderwhy-er/desktop-commander@latest remote
```

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

### Usage example for validateCommand

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/command-manager.md

Shows how to import and use commandManager.validateCommand. The first example checks a chained command, the second extracts commands from a substitution, and the third demonstrates a blocked command.

```typescript
import { commandManager } from './src/command-manager.js';

const allowed = await commandManager.validateCommand('npm run build && echo done');
// false when any extracted base command (npm, echo) is blocked

const allowed2 = await commandManager.validateCommand('echo $(sudo ls /etc)');
// extracts: ['echo', 'sudo', 'ls'] — blocked when 'sudo' is on the list

const blocked = await commandManager.validateCommand('sudo rm -rf /');
// -> false with the default blocklist
```

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

### Install server in debug mode

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Install the server in debug mode using either npx or the local npm script. This configures Claude to use a separate 'desktop-commander' server, enables the Node.js inspector protocol with the --inspect-brk=9229 flag, pauses execution at startup until a debugger connects, and enables additional debugging environment variables.

```bash
npx @wonderwhy-er/desktop-commander@latest setup --debug
```

```bash
npm run setup:debug
```

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

### Standard MCP configuration for other clients

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Standard JSON configuration for installing Desktop Commander in any MCP-compatible client. Add this to your client's MCP configuration file.

```json
{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@wonderwhy-er/desktop-commander@latest"]
    }
  }
}
```

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

### startSearch(options)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/search-manager.md

Starts a new search session with the given options. Validates the root path, spawns ripgrep, and returns after the first data chunk (max 40 ms wait). For content searches, it may also fan out to Excel/DOCX file searches in the background.

```APIDOC
## startSearch(options)

### Description
Starts a new search session with the given options. Validates the root path, spawns ripgrep, and returns after the first data chunk (max 40 ms wait). For content searches, it may also fan out to Excel/DOCX file searches in the background.

### Method
async

### Endpoint
`startSearch(options: SearchSessionOptions): Promise<{ sessionId: string; isComplete: boolean; isError: boolean; results: SearchResult[]; totalResults: number; runtime: number; }>`

### Parameters
#### Request Body
- **options** (SearchSessionOptions) - Required - The search options object.
  - **rootPath** (string) - Required - The root directory to search in.
  - **pattern** (string) - Required - The search pattern (regex or literal).
  - **searchType** ('files' | 'content') - Required - Whether to search file names or file contents.
  - **filePattern** (string) - Optional - File pattern to filter files.
  - **ignoreCase** (boolean) - Optional - Whether to ignore case.
  - **maxResults** (number) - Optional - Maximum number of results to return.
  - **includeHidden** (boolean) - Optional - Whether to include hidden files.
  - **contextLines** (number) - Optional - Number of context lines to include.
  - **timeout** (number) - Optional - Timeout in milliseconds. Defaults to 1500 for exact filename searches, otherwise undefined.
  - **earlyTermination** (boolean) - Optional - Stop search early when exact filename match is found.
  - **literalSearch** (boolean) - Optional - Force literal string matching (-F flag) instead of regex.

### Request Example
```json
{
  "rootPath": "/workspace/home",
  "pattern": "TODO",
  "searchType": "content",
  "ignoreCase": true,
  "contextLines": 3
}
```

### Response
#### Success Response (200)
- **sessionId** (string) - The session ID in the form `search_<counter>_<epochMs>`.
- **isComplete** (boolean) - Whether the search is complete.
- **isError** (boolean) - Whether an error occurred.
- **results** (SearchResult[]) - Array of search results.
- **totalResults** (number) - Total number of results.
- **runtime** (number) - Runtime in milliseconds.

#### Response Example
```json
{
  "sessionId": "search_1_1623456789012",
  "isComplete": false,
  "isError": false,
  "results": [],
  "totalResults": 0,
  "runtime": 12
}
```

### Error Handling
- Throws `Error("Failed to locate ripgrep binary: ...")` if ripgrep is not found.
- Throws `Error('Failed to start ripgrep process')` if the process fails to start.
- Throws on invalid root paths (via `validatePath`).
```

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

### Usage example for config, usage, prompts, and feedback tools

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/misc-tools.md

Shows how to call the config, usage, prompts, and feedback tools. Note that setConfigValue coerces arrays and validates boolean values; config/prompts/usage tools return isError results instead of throwing, and setConfigValue reports save-to-disk failures as isError while keeping the in-memory change.

```ts
import { getConfig, setConfigValue } from './src/tools/config.js';
import { getUsageStats } from './src/tools/usage.js';
import { getPrompts } from './src/tools/prompts.js';
import { giveFeedbackToDesktopCommander } from './src/tools/feedback.js';

const cfg = await getConfig();
const uiEntries = cfg.structuredContent?.entries;   // [{ key, value, valueType, editable }]

await setConfigValue({ key: 'blockedCommands', value: ['rm'] });       // array coercion
const bad = await setConfigValue({ key: 'telemetryEnabled', value: 'yes' }); // isError: must be true/false

const stats = await getUsageStats();
const prompt = await getPrompts({ action: 'get_prompt', promptId: 'onb2_01' });
await giveFeedbackToDesktopCommander();
```

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

### Install Hermes CLI on Linux/macOS/WSL2/Android

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/skills/ai-tools-setup/references/hermes.md

Installs the Hermes CLI using a curl pipe to bash. Suitable for Linux, macOS, WSL2, and Android (Termux).

```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

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

### startSearch method signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/search-manager.md

Method signature for starting a search. Validates the root path, spawns ripgrep, and returns after the first data chunk. Throws errors for invalid roots, missing ripgrep, or spawn failure.

```ts
async startSearch(options: SearchSessionOptions): Promise<{
  sessionId: string;
  isComplete: boolean;
  isError: boolean;
  results: SearchResult[];
  totalResults: number;
  runtime: number;
}>
```

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

### Data Analysis Command Example

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Example of a natural language command for data analysis using Desktop Commander. Claude runs Python code in memory to analyze the CSV file.

```text
"Analyze sales.csv and show top customers" → Claude runs Python code in memory
```

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

### Managing and Interacting with Processes

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/process-tools.md

Demonstrates the workflow for starting a process, sending input, reading output, and terminating it, alongside listing and killing processes. All operations return a ServerResult object with an isError property for error handling.

```ts
import { startProcess, interactWithProcess, readProcessOutput, forceTerminate } from './src/tools/improved-process-tools.js';
import { listProcesses, killProcess } from './src/tools/process.js';

const started = await startProcess({ command: 'python3 -i', timeout_ms: 10000 });
if (started.isError) { /* blocked or invalid — take the message and stop */ }
// started.content[0].text contains "Process started with PID 123 ..."

const reply = await interactWithProcess({ pid: 123, input: 'print(2+2)\n', wait_for_prompt: true });
const out = await readProcessOutput({ pid: 123, offset: 0, length: 100 });
await forceTerminate({ pid: 123 });

const procs = await listProcesses();
await killProcess({ pid: 456 });
```

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

### start_search

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/endpoints.md

Starts a background search session for files or content. Returns session ID and first 10 results. Poll with `get_more_search_results`.

```APIDOC
## start_search

### Description
Starts a background search session for files or content. Returns session ID and first 10 results. Poll with `get_more_search_results`.

### Method
MCP Tool Call

### Endpoint
`start_search`

### Parameters
#### Request Body
- **type** (string) - Required - `files` or `content`.
- **pattern** (string) - Required - Search pattern.
- **path** (string) - Required - Path to search.

### Response
#### Success Response
- **message** (string) - `Started <files|content> search session: <id>`.
- **content** (array) - Pattern, path, status, runtime, and first 10 results.

#### Response Example
```json
{
  "message": "Started files search session: abc123"
}
```
```

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

### getPrompts function signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/misc-tools.md

Simplified onboarding prompt API supporting only action: 'get_prompt'. Missing action returns '❌ Error: 'action' parameter is required. Use 'get_prompt'' (isError); action without promptId returns '❌ Error: promptId is required when action is 'get_prompt'' (isError); unknown/legacy actions return '❌ Error: Only 'get_prompt' action is supported. Use promptId to get a specific prompt.' (isError). Valid action looks up the prompt in onboarding-prompts.json (category onboarding; known ids onb2_01…onb2_05) and returns the formatted prompt; unknown id returns '❌ Prompt with ID '<id>' not found. ...' (isError). Also calls usageTracker.markPromptUsed(promptId, category).

```ts
export async function getPrompts(params: any): Promise<ServerResult>
```

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

### Import and use utility functions from src/utils

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/utils.md

Shows how to import and use the utility functions from src/utils. withTimeout rejects with a timeout message, runWithAbortableTimeout throws an ETIMEDOUT error on abort, capture swallows network failures, logger falls back to raw JSON lines, and featureFlagManager.initialize() must be called before get().

```ts
import { withTimeout, runWithAbortableTimeout } from './src/utils/withTimeout.js';
import { logger } from './src/utils/logger.js';
import { capture, sanitizeError } from './src/utils/capture.js';
import { featureFlagManager } from './src/utils/feature-flags.js';
import { detectUnsupportedParams } from './src/utils/unsupportedParams.js';

const value = await withTimeout(somePromise, 5000, 'my operation', null);
// rejects "__ERROR__: my operation timed out after 5 seconds" on timeout

const read = await runWithAbortableTimeout((signal) => fs.readFile(p, { signal }), 3000, 'read');
// throws Error with .code === 'ETIMEDOUT' when aborted

logger.info('startup complete');
await capture('my_event', { n: 1 });
const clean = sanitizeError(err);                       // paths → [PATH]

await featureFlagManager.initialize();
const showUi = featureFlagManager.get('showWidget', false);
```

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

### Interactive REPL pattern with start_process and interact_with_process

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/claude/skills/terminal/SKILL.md

Drives an interactive REPL (Python, Node, SSH, psql) across calls. Start with start_process, send input with interact_with_process, read responses with read_process_output, and force_terminate if it won't exit on its own.

```python
start_process("python3 -i")          # or "node -i", "ssh user@host", "psql ..."
interact_with_process(pid, "import pandas as pd")
interact_with_process(pid, "df = pd.read_csv('/abs/path/data.csv')")
interact_with_process(pid, "print(df.describe())")
read_process_output(pid)             # pull more output if needed
```

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

### Run Remote Device with auto-restart during development

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/src/remote-device/README.md

Starts the Remote Device with automatic restart on file changes, ideal for active development. Requires the development server to be running.

```bash
npm run device:start:dev
```

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

### Configure fileWriteLineLimit with set_config_value

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/FAQ.md

Shows how to adjust the fileWriteLineLimit setting using the set_config_value function. The first example sets a high value (2000) to allow larger writes, while the second sets a smaller value (25) to encourage more efficient, chunked behavior. The default is 50 lines.

```javascript
// You can set it very high if needed
set_config_value({ "key": "fileWriteLineLimit", "value": 2000 })

// Or keep it small to force efficient behavior
set_config_value({ "key": "fileWriteLineLimit", "value": 25 })
```

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

### getPrompts

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/misc-tools.md

Simplified onboarding prompt API supporting only the `get_prompt` action.

```APIDOC
## getPrompts

### Description
Simplified onboarding prompt API supporting only the `get_prompt` action. Returns a formatted prompt based on the provided promptId.

### Method
Not applicable (function call)

### Endpoint
Not applicable (function call)

### Parameters
- **params** (any) - Required - Object containing `action` and `promptId`.
  - `action` (string) - Required - Must be `'get_prompt'`.
  - `promptId` (string) - Required when action is `'get_prompt'` - The ID of the prompt to retrieve (known ids: `onb2_01`...`onb2_05`).

### Returns
- **ServerResult** - Formatted prompt text; on error, returns error text with isError flag.

### Error Handling
- Missing `action` → `❌ Error: 'action' parameter is required. Use 'get_prompt'` (isError).
- `action: 'get_prompt'` without `promptId` → `❌ Error: promptId is required when action is 'get_prompt'` (isError).
- Unknown/legacy actions → `❌ Error: Only 'get_prompt' action is supported. Use promptId to get a specific prompt.` (isError).
- Unknown promptId → `❌ Prompt with ID '<id>' not found. ...` (isError).

### Example
```ts
const result = await getPrompts({ action: 'get_prompt', promptId: 'onb2_01' });
```
```

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

### Cleanup commands: empty trash, cache, package cache, updates, startup items

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/cursor/skills/computer-health-check/references/linux.md

Suggest these commands; run only on approval. Empty Trash is safe, user cache review is safe, package cache and updates typically need sudo, startup items are user action.

```bash
rm -rf "$HOME/.local/share/Trash/"*
```

```bash
du -sh ~/.cache/* | sort -rh | head
```

```bash
apt-get clean
```

```bash
dnf clean all
```

```bash
pacman -Sc
```

```bash
apt upgrade
```

```bash
dnf upgrade
```

```bash
pacman -Syu
```

```bash
systemctl --user disable <unit>
```

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

### Release plan output

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/PUBLISH.md

The script displays this plan and asks for confirmation before proceeding. The plan outlines the steps: run tests, bump version, push main and tag, and the CI release steps.

```text
Release plan:
  1. Run tests (local, nothing changed yet)
  2. Bump version 0.2.47 → 0.2.48 and commit
  3. Push main + tag v0.2.48 to origin — this starts the CI release:
     build MCPB → publish npm → GitHub release with .mcpb asset
     (picked up by the Claude directory) → publish MCP Registry

Release v0.2.48 now? [y/N]
```

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

### JSON-RPC notification/message example

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/CLINE_NOTIFICATION_PROBLEM.md

Example of the JSON-RPC notification used by Desktop Commander to send log messages. Cline displays these notifications in the UI, causing visual clutter.

```json
{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "info",
    "logger": "desktop-commander",
    "data": "Your log message here"
  }
}
```

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

### Filesystem tools usage: validatePath, readFile, writeFile, listDirectory, getFileInfo

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/filesystem-tools.md

Shows how to import and use the filesystem tools: validatePath throws on disallowed paths, readFile reads with offset/length, writeFile writes with a rewrite mode, listDirectory returns entries with a depth limit, and getFileInfo retrieves file metadata. Most functions throw Error on failures, but readMultipleFiles and getDefaultEditorMetadata never throw.

```ts
import {
  validatePath, readFile, writeFile, listDirectory,
  getFileInfo, getDefaultEditorMetadata,
} from './src/tools/filesystem.js';

const valid = await validatePath('~/notes/todo.txt');   // throws when not allowed
const result = await readFile(valid, { offset: 0, length: 100 });
console.log(result.content, result.metadata);

await writeFile('/tmp/out.txt', 'line 1\n', 'rewrite');
const entries = await listDirectory('/tmp', 2);        // ["[DIR] out.txt", ...]
const info = await getFileInfo('/tmp/out.txt');
```

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

### new MCPDevice(options?)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/remote-device.md

Constructor for the MCPDevice class. Initializes the remote channel, desktop integration, graceful shutdown handlers, and session persistence settings.

```APIDOC
## Constructor: `new MCPDevice(options?)`

### Description
Creates a new MCPDevice instance that connects to the hosted Remote MCP service and relays tool calls to the local Desktop Commander MCP server.

### Parameters
- **options** (MCPDeviceOptions) - Optional - Configuration object with the following properties:
  - **persistSession** (boolean) - Optional - Defaults to `true`. When `false`, forces full re-authorization on every start.

### Behavior
- Uses `process.env.MCP_SERVER_URL || 'https://mcp.desktopcommander.app'` as the base server URL.
- Builds a `RemoteChannel`, a `DesktopCommanderIntegration`, and wires session refresh to config persistence.
- Installs SIGINT/SIGTERM graceful shutdown handlers (5 second force-exit; multiple signals exit with code 1).

### Example
```ts
const device = new MCPDevice({ persistSession: true });
```

```

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

### ConfigManager.loadConfig()

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/config-manager.md

Alias of `init()` kept for backward compatibility. Loads the configuration from disk.

```APIDOC
## ConfigManager.loadConfig()

### Description
Alias of `init()` kept for backward compatibility.

### Method
loadConfig

### Signature
`async loadConfig()`

### Parameters
None

### Returns
`Promise<void>`

### Example
```ts
await configManager.loadConfig();
```
```

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

### bufferedMessageCount (getter)

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/CUSTOM_STDIO_EXPLANATION.md

Gets the count of buffered messages.

```APIDOC
## bufferedMessageCount

### Description
Gets the count of buffered messages.

### Method
bufferedMessageCount (getter)

### Parameters
None

### Returns
number

```

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

### Batched system health collection script

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/plugins/claude/skills/computer-health-check/references/macos.md

Run with start_process (timeout ~30s). Prints labeled sections for parsing. Covers system, hardware, disk, memory, top CPU/mem, battery, thermal, startup, storage hotspots, packages, and crash reports.

```bash
zsh -c '
echo "== SYSTEM =="; sw_vers; echo "uptime:"; uptime
echo "== HARDWARE =="; system_profiler SPHardwareDataType 2>/dev/null | grep -Ei "Model Name|Chip|Total Number of Cores|Memory:"
echo "== DISK =="; df -h /
diskutil info / 2>/dev/null | grep -Ei "SMART|Free Space"
echo "== MEMORY =="; vm_stat | head -n 8
echo "swap:"; sysctl -n vm.swapusage
echo "== TOP CPU =="; ps -Ao pid,pcpu,pmem,comm -r | head -n 8
echo "== TOP MEM =="; ps -Ao pid,pcpu,pmem,comm -m | head -n 8
echo "== BATTERY =="; pmset -g batt | head -n 2
system_profiler SPPowerDataType 2>/dev/null | grep -Ei "Cycle Count|Condition|Maximum Capacity"
echo "== THERMAL =="; pmset -g therm 2>/dev/null | head -n 3
echo "== STARTUP =="; echo "user agents:"; ls -1 "$HOME/Library/LaunchAgents" 2>/dev/null
echo "service count: $(launchctl list 2>/dev/null | wc -l | tr -d " ")"
echo "== STORAGE HOTSPOTS =="
for d in "$HOME/Downloads" "$HOME/Library/Caches" "$HOME/.Trash" "$HOME/Library/Logs"; do
  [ -d "$d" ] && printf "%s\t%s\n" "$(du -sh "$d" 2>/dev/null | cut -f1)" "${d/#$HOME/~}"
done
echo "== PACKAGES =="
command -v brew >/dev/null 2>&1 && echo "brew outdated: $(brew outdated 2>/dev/null | wc -l | tr -d " "), cache: $(du -sh "$(brew --cache)" 2>/dev/null | cut -f1)" || echo "brew: not installed"
echo "== CRASH REPORTS =="; ls -1 "$HOME/Library/Logs/DiagnosticReports" 2>/dev/null | wc -l
echo "== DONE =="'
```

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

### ConfigManager.isFirstRun()

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/config-manager.md

Indicates whether the configuration file was just created during initialization.

```APIDOC
## ConfigManager.isFirstRun()

### Description
True when the config file was just created during this process's `init()`.

### Method
isFirstRun

### Signature
`isFirstRun(): boolean`

### Parameters
None

### Returns
`boolean` - True if the config file was just created during initialization.

### Example
```ts
const firstRun = configManager.isFirstRun();
```
```

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

### readProcessOutput

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/process-tools.md

Reads output from a process starting at a given offset and with a specified length.

```APIDOC
## readProcessOutput

### Description
Reads output from a process starting at a given offset and with a specified length.

### Parameters
- **pid** (number) - Required - The process ID.
- **offset** (number) - Required - The byte offset to start reading from.
- **length** (number) - Required - The number of bytes to read.

### Returns
- **ServerResult** - On success, contains the process output. On failure, `isError` is `true`.

### Example
```ts
const out = await readProcessOutput({ pid: 123, offset: 0, length: 100 });
```
```

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

### Reset and reinstall Docker

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Troubleshooting command to reset and reinstall Docker from scratch on macOS/Linux.

```bash
bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh) --reset && bash <(curl -fsSL https://raw.githubusercontent.com/wonderwhy-er/DesktopCommanderMCP/refs/heads/main/install-docker.sh)
```

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

### isFirstRun() method signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/config-manager.md

Returns true when the config file was just created during this process's init().

```typescript
isFirstRun(): boolean
```

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

### getOutputLineCount method signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/terminal-manager.md

Method signature for getting the line count of the active or completed session buffer.

```ts
getOutputLineCount(pid: number): number | null
```

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

### MCPDeviceOptions interface

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/remote-device.md

Options interface for MCPDevice. The persistSession flag defaults to true; setting it to false forces full re-authorization on every start.

```ts
export interface MCPDeviceOptions {
    persistSession?: boolean;
}
```

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

### getOutputSinceSnapshot method signature

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/_autodocs/api-reference/terminal-manager.md

Method signature for getting output produced since a snapshot. Handles REPL prompt-line appends and completed sessions.

```ts
getOutputSinceSnapshot(pid: number,
  snapshot: { totalChars: number; lineCount: number }): string | null
```

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

### Remove desktop-commander entry from Claude config

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Example section to remove from the mcpServers section of the Claude Desktop config file when manually uninstalling Desktop Commander.

```json
{
    "desktop-commander": {
      "command": "npx",
      "args": ["@wonderwhy-er/desktop-commander@latest"]
    }
}
```

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

### Add Desktop Commander to Claude Code

Source: https://github.com/wonderwhy-er/desktopcommandermcp/blob/main/README.md

Command to add Desktop Commander MCP to Claude Code. Remove --scope user to install for the current project only.

```sh
claude mcp add --scope user desktop-commander -- npx -y @wonderwhy-er/desktop-commander@latest
```
Tokens:
Raw