# DesktopCommanderMCP API: Complete Guide to MCP Tools and Endpoints

> Explore the DesktopCommanderMCP API, a powerful tool with 25+ endpoints for AI clients. Execute commands, manage files, processes, and search codebases with this comprehensive guide.

- Repository: [Eduard Ruzga/DesktopCommanderMCP](https://github.com/wonderwhy-er/DesktopCommanderMCP)
- Tags: api-reference
- Published: 2026-07-16

---

**DesktopCommanderMCP exposes a comprehensive Model Context Protocol (MCP) API with 25+ tool endpoints that enable AI clients to execute terminal commands, manipulate files (including PDFs and Excel), manage processes, and search codebases.**

DesktopCommanderMCP is a Node.js-based MCP server that transforms Claude and other MCP-compatible clients into full-featured development assistants. According to the `wonderwhy-er/DesktopCommanderMCP` source code, the API communicates over WebSocket or Supabase realtime transports and exposes functionality through structured JSON tool calls defined in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts).


## How the DesktopCommanderMCP API Works

The DesktopCommanderMCP API implements the **Model Context Protocol (MCP)** specification, running as a persistent Node.js process that listens for tool invocations. Clients such as Claude Desktop, Cursor, or VS Code Copilot send JSON payloads over the MCP transport layer, and the server executes the corresponding logic in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts) (lines 665-883) before returning structured result objects.

Each API call follows a standard request format:

```json
{
  "tool_name": "<api_method>",
  "tool_args": { ...parameters }
}

```

Responses contain an array of content blocks, typically with `type` and `text` or `data` properties containing the operation results.


## Configuration Management API

The configuration API controls server behavior and security policies through two primary endpoints.

**`get_config`** returns the full server state including blocked commands, default shell, allowed directories, and telemetry settings.

**`set_config_value`** updates individual configuration keys atomically and persists changes to [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json).

```json
{
  "tool_name": "get_config",
  "tool_args": {}
}

```

```json
{
  "tool_name": "set_config_value",
  "tool_args": {
    "key": "telemetryEnabled",
    "value": false
  }
}

```


## Terminal and Process Control API

DesktopCommanderMCP provides comprehensive process management through seven dedicated endpoints defined in the server implementation.

**Process lifecycle management:**
- **`start_process`** – Launches interactive processes (Node, Python, Bash) and returns a unique session ID
- **`interact_with_process`** – Sends stdin input to running processes and streams stdout back to the client
- **`read_process_output`** – Pulls buffered output from a specific PID without blocking
- **`force_terminate`** – Immediately kills a running process
- **`list_sessions`** – Enumerates all active terminal sessions

**System process inspection:**
- **`list_processes`** – Returns an OS-level snapshot of visible processes
- **`kill_process`** – Terminates processes by PID with graceful cleanup

```json
{
  "tool_name": "start_process",
  "tool_args": {
    "command": "python",
    "args": ["-i"]
  }
}

```

```json
{
  "tool_name": "interact_with_process",
  "tool_args": {
    "pid": "<session-id>",
    "input": "print('Hello from MCP')\n"
  }
}

```


## Filesystem Operations API

The filesystem API supports complex document types beyond plain text, implementing specialized handlers for Excel and PDF formats in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts).

**File reading capabilities:**
- **`read_file`** – Reads text, Excel (.xlsx/.xls/.xlsm), PDF, and DOCX with pagination support via `offset` and `length` parameters; can fetch remote URLs
- **`read_multiple_files`** – Parallel file reading for batch operations
- **`get_file_info`** – Returns metadata including size, timestamps, and Excel sheet structures

**File writing and manipulation:**
- **`write_file`** – Writes or appends text; supports Excel-style 2D JSON arrays for spreadsheet generation
- **`write_pdf`** – Creates PDFs from Markdown/HTML or modifies existing PDFs (add/remove pages, SVG graphics)
- **`create_directory`** – Idempotent directory creation
- **`list_directory`** – Recursive listing with configurable depth and overflow protection
- **`move_file`** – Atomic rename/move operations

```json
{
  "tool_name": "read_file",
  "tool_args": {
    "path": "/home/user/data/sales.csv",
    "offset": 0,
    "length": 200
  }
}

```

```json
{
  "tool_name": "write_pdf",
  "tool_args": {
    "content": "# Markdown Header\n\nDocument body",

    "output_path": "/home/user/report.pdf"
  }
}

```


## Search and Discovery API

DesktopCommanderMCP integrates **ripgrep** for high-performance codebase searching with Excel cell indexing capabilities.

**Search session management:**
- **`start_search`** – Initiates streaming content/name searches with optional Excel cell traversal
- **`get_more_search_results`** – Paginates through search results using `offset` and `limit`
- **`stop_search`** – Gracefully aborts ongoing searches
- **`list_searches`** – Displays all active search sessions

```json
{
  "tool_name": "start_search",
  "tool_args": {
    "query": "TODO",
    "path": "/home/user/projects",
    "include_excel": true
  }
}

```

```json
{
  "tool_name": "get_more_search_results",
  "tool_args": {
    "search_id": "<search-uuid>",
    "offset": 100,
    "length": 100
  }
}

```


## Text Editing API

The **`edit_block`** endpoint performs surgical text replacements using block-replace syntax, functioning as a precise code modification tool that supports both plain text updates and Excel cell modifications.

```json
{
  "tool_name": "edit_block",
  "tool_args": {
    "filepath": "src/main.js",
    "search": "console.log('old message');",
    "replace": "console.log('new message');"
  }
}

```

The server returns a diff-formatted response showing exactly what changed:

```json
{
  "content": [
    {
      "type": "text",
      "text": "{-console.log('old message');-}{+console.log('new message');+}"
    }
  ]
}

```


## Analytics and Debugging API

Three endpoints provide operational visibility into the DesktopCommanderMCP server.

**`get_usage_stats`** returns current device utilization metrics and command execution history.

**`get_recent_tool_calls`** retrieves the recent tool-call history including full argument payloads and output results for debugging purposes.

**`give_feedback_to_desktop_commander`** opens a browser-based feedback form for user input collection.


## Key Implementation Files

The DesktopCommanderMCP API is implemented across several critical source files:

- **[`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts)** – Core MCP server containing the tool dispatch table (lines 665-883) and business logic implementations
- **[`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts)** – Thin client wrapper (lines 16-89) that establishes the Supabase-based MCP channel and handles device authentication
- **[`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml)** – MCP server declaration consumed by Claude Desktop, defining the command `npx @wonderwhy-er/desktop-commander@latest`
- **[`package.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/package.json)** – Package metadata and exported command definitions

These files collectively define the public API contract and transport layer specifications.


## Summary

- DesktopCommanderMCP exposes 25+ tool-call APIs over the Model Context Protocol, enabling AI clients to perform filesystem operations, process management, and code editing.
- The API supports complex document types including Excel spreadsheets and PDFs through specialized handlers in [`src/server.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/server.ts).
- Terminal interaction uses session-based process management with `start_process`, `interact_with_process`, and `force_terminate`.
- Codebase search leverages ripgrep with Excel cell traversal capabilities via `start_search` and pagination controls.
- Configuration changes persist atomically to [`config.json`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/config.json) through `set_config_value` and `get_config`.


## Frequently Asked Questions

### What is DesktopCommanderMCP API used for?

DesktopCommanderMCP API transforms MCP-compatible AI clients like Claude into full-featured development assistants by exposing tools for terminal command execution, file manipulation (including binary formats like PDF and Excel), codebase searching, and surgical text editing. The API enables programmatic control over the local development environment through structured JSON tool calls.

### How do I authenticate with DesktopCommanderMCP API?

Authentication is handled through the [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts) component, which establishes a Supabase realtime connection and validates device identity before forwarding tool calls to the main server. Clients using Claude Desktop or Cursor authenticate automatically when the MCP server starts via the [`plugin.yaml`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/plugin.yaml) configuration, which specifies the launch command `npx @wonderwhy-er/desktop-commander@latest`.

### Can DesktopCommanderMCP handle Excel and PDF files?

Yes, the API includes specialized handlers for binary document formats. The `read_file` tool parses Excel cells and PDF content with pagination support, while `write_file` accepts 2D JSON arrays for spreadsheet creation and `write_pdf` generates PDFs from Markdown or HTML. The `edit_block` tool can also target specific Excel cells for updating spreadsheet data.

### What transport protocols does DesktopCommanderMCP API support?

The API communicates over **Model Context Protocol (MCP)** transports, specifically WebSocket connections and **Supabase realtime** channels as implemented in [`src/remote-device/device.ts`](https://github.com/wonderwhy-er/DesktopCommanderMCP/blob/main/src/remote-device/device.ts). This architecture allows the Node.js server to handle concurrent tool calls from multiple AI clients while maintaining persistent terminal sessions and search states.