DesktopCommanderMCP API: Complete Guide to MCP Tools and Endpoints

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.

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 (lines 665-883) before returning structured result objects.

Each API call follows a standard request format:

{
  "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.

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

{
  "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

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

{
  "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.

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

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

{
  "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

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

{
  "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.

{
  "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:

{
  "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 – Core MCP server containing the tool dispatch table (lines 665-883) and business logic implementations
• src/remote-device/device.ts – Thin client wrapper (lines 16-89) that establishes the Supabase-based MCP channel and handles device authentication
• plugin.yaml – MCP server declaration consumed by Claude Desktop, defining the command npx @wonderwhy-er/desktop-commander@latest
• 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.
• 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 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 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 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. This architecture allows the Node.js server to handle concurrent tool calls from multiple AI clients while maintaining persistent terminal sessions and search states.

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