DOCSEARCHbyAlgolia
Submit Docs

Desktop Commander MCP Server

repository·main·Indexed 25 days ago

https://github.com/wonderwhy-er/desktopcommandermcp

An MCP server and Claude Code plugin providing AI agents access to local terminal sessions, filesystem operations, and system health monitoring. It includes specialized skills for managing persistent shells, SSH, Windows PowerShell, and knowledge management via Obsidian vault integration. The package also features a Remote Device bridge for secure connections between remote AI and local machines, and a FilteredStdioServerTransport for MCP protocol-compliant logging.

Tokens
38.2K
Snippets
58
Records
198
Agent score
93%

What's inside Desktop Commander

  1. Overview of Claude Desktop Commander

    main

    Claude Desktop Commander is an MCP (Model Context Protocol) tool that enables Claude Desktop to interact with your computer's operating system. It allows Claude to:

    • Explore, read, and write files.
    • Execute terminal commands.
    • Manage processes.

    Unlike IDE-centric tools (like Cursor or Windsurf) that focus on chunking and indexing files for coding, Desktop Commander provides a system-wide approach, allowing Claude to work across your entire OS, generate diagrams in chat, and execute multi-step automation processes.

  2. Overview of Desktop Commander MCP capabilities

    main

    Desktop Commander MCP provides an agent with extended reach across a user's computer, including files, terminals, processes, and remote machines. Key capabilities include:

    • Persistent Shell Sessions: Maintains state (environment variables, working directory, virtualenvs, REPL variables) within a single session across multiple tool calls.
    • Long-running Processes: Allows starting background tasks (dev servers, builds, tests) and interacting with them via a process handle.
    • Extended Filesystem Access: Read, write, and manage files outside the immediate IDE workspace (e.g., Downloads, Documents).
    • Surgical File Edits: Uses edit_block for safe, exact-string find-and-replace to minimize data loss.
    • Structured File Support: Direct handling of Excel (.xlsx), DOCX, and PDF files using format-specific mechanisms rather than text approximations.
    • Scalable Search: Uses ripgrep-backed streaming search for filenames and content across large directory trees.
    • Remote Access: Supports long-lived SSH sessions for remote operations.
    • Process Management: Ability to list, inspect, tail, and terminate OS processes.

  3. Understand the Computer Health Check skill

    main

    The computer-health-check skill provides a comprehensive, read-only diagnostic of a user's computer. It is designed to detect system health, speed, disk space, CPU/memory usage, battery health, startup items, and pending updates. It works across macOS, Windows, and Linux by utilizing Desktop Commander's local shell capabilities (start_process / interact_with_process).

    Key Characteristics:

    • Read-only by default: The collection phase only observes system state and does not change anything.
    • No elevation required: The skill is designed to work without sudo or administrative privileges. It avoids commands like shutdown, reboot, dd, mount, mkfs, or diskpart which are blocked by Desktop Commander.
    • Opt-in cleanups: While the skill can suggest cleanup actions, it will only execute them after explicit user approval of the specific command.

  4. Understand Desktop Commander telemetry data collection

    main

    Desktop Commander collects limited, pseudonymous telemetry data to improve the tool.

    What is collected:

    • Pseudonymous Client ID: A random UUID used for retention and usage metrics (not derived from hardware).
    • Application Usage Events: Event names, timestamps, OS type, app version, and MCP client info (e.g., "Claude Desktop").
    • Installation/Setup Info: Node.js/NPM versions, installation method (npx, global, etc.), shell type, and setup status.
    • Environment Metadata: Container detection (Docker/Kubernetes) and runtime source.
    • File Operation Metrics: File extensions, file sizes, operation types (read, write, edit), and status.
    • Terminal Command Metrics: Base command name (e.g., "python"), execution time, and status.
    • Error Information: Error types, system error codes, and sanitized error messages.

    What is NOT collected:

    • File paths or filenames
    • File contents
    • Command arguments or parameters
    • Usernames (system or account)
    • Personally identifiable information (PII)
    • IP Addresses (anonymized by Google Analytics before storage)

  8. Cleanup Windows system files and packages

    main

    The following commands can be used for system maintenance. Note: Run these only upon user approval.

    • Empty Recycle Bin: Clear-RecycleBin -Force (PowerShell).
    • Temp Files: Remove contents of $env:TEMP. It is recommended to show the size first using: (Get-ChildItem $env:TEMP -Recurse -EA SilentlyContinue | Measure Length -Sum).Sum/1GB.
    • Package Upgrades: winget upgrade --all (may require elevation/prompting).
    • Manual Actions:
      • Startup items: Use Task Manager (Startup tab) or Settings → Apps → Startup.
      • Windows Updates: Use Settings → Windows Update.
      • Disk Cleanup: Run cleanmgr for system-level reclamation.

  9. Convert workflows into scripts

    main

    To automate repeated terminal workflows, offer to save them as scripts using write_file to an absolute path.

    Unix (bash/zsh)

    • Use a .sh file.
    • Include #!/usr/bin/env bash (or zsh).
    • Use set -euo pipefail for safety.
    • Make the file executable with chmod +x.

    Windows (PowerShell)

    • Use a .ps1 file.
    • Include comment-based help at the top.

    Best Practices

    • Parameterize variables (paths, names) instead of hard-coding.
    • If a workflow must be cross-platform, provide both a .sh and a .ps1 file, or use a cross-platform language like Python or Node.

  10. Handle destructive commands safely

    main

    Desktop Commander has a built-in blockedCommands list (e.g., sudo, mkfs, format, dd, fdisk, shutdown, reboot, diskpart, reg, net). Always check get_config for the live list.

    Mandatory Confirmation Required: Never run the following without explicit user confirmation:

    • Recursive/forced deletes: rm -rf, Remove-Item -Recurse -Force, del /s, rd /s.
    • Overwriting files or wildcard deletes.
    • Git destructive operations: git reset --hard, git clean -fd, git push --force.
    • Database operations: DROP, TRUNCATE, DELETE without a WHERE clause.
    • Mass process kills or broad chmod -R / chown -R operations.
    • Cloud/Docker destructive actions: docker system prune, docker rm, docker volume rm, or IAM/scaling changes.
    • Piping remote content into a shell: curl ... | sh.

    Best Practice: Use a dry run (e.g., --dry-run) or a read-only check (e.g., ls before rm) first.

  12. Use Wikilinks for Obsidian navigation

    main

    Obsidian uses wikilinks ([[Note title]]) for internal navigation. These resolve by filename, not path.

    • Display text: Use a pipe to show different text: [[atomic-habits|James Clear — Atomic Habits]].
    • Heading/Block links: Link to specific sections using [[Note#Section]] or blocks using [[Note#^block-id]].
    • Embeds/Transclusions: Use an exclamation mark to embed content: ![[Note]] or ![[image.png]].
    • Aliases: To allow a note to be found by multiple names, add an aliases property to its YAML frontmatter.
    • Filename Restrictions: Avoid using #, |, ^, :, %, or [ ] in filenames as they have special meanings in links.

    Note: When adding links, look for unlinked mentions (instances where the note's title appears as plain text) and convert them to wikilinks to strengthen the graph.