🖥️ Desktop Commander MCP

Portable, general-purpose filesystem + terminal tools for MCP clients

Search files · edit documents · run commands · manage processes · inspect the local workspace

English · 简体中文

A community-maintained portable adaptation of Desktop Commander MCP.
It is designed for standard stdio-compatible MCP clients and does not depend on any vendor-specific deployment platform.

✨ Highlights

Related MCP server: Windows-MCP

🚀 Quick start

1. Clone

git clone https://github.com/luffy666code/desktop-commander-mcp.git
cd desktop-commander-mcp

2. Install and build

npm install
npm run build

Requirements: Node.js 18+ and npm.

3. Verify the search engine

npm run verify:rg

4. Add it to your MCP client

Use the standard stdio configuration pattern:

{
  "mcpServers": {
    "desktop-commander": {
      "command": "node",
      "args": ["/absolute/path/to/desktop-commander-mcp/dist/index.js"]
    }
  }
}

Replace the path with the real absolute path on your machine. See Client setup for Windows path examples and Inspector usage.

🧭 How it works

MCP client
   │
   │ stdio / MCP requests
   ▼
dist/index.js
   │
   ▼
server + tool handlers
   │
   ├── filesystem operations
   ├── terminal / process manager
   ├── document utilities
   └── search manager
          │
          ▼
       ripgrep

The ripgrep resolver first checks the platform-correct binary in @vscode/ripgrep, then falls back to the package export, the system PATH, and common installation locations. On Unix-like systems it also verifies executable permission.

🔐 Safety defaults

config.json ships with a conservative blocklist for destructive or privilege-escalating commands such as format, mkfs, fdisk, dd, sudo, and user-management commands.

{
  "blockedCommands": [
    "format", "mount", "umount", "mkfs", "fdisk", "dd",
    "sudo", "su", "passwd", "adduser", "useradd", "usermod", "groupadd"
  ]
}

This is a guardrail, not a sandbox. Review SECURITY.md before using command execution against important data or production machines.

🛠️ Development

# TypeScript watch mode
npm run watch

# Run from TypeScript during development
npm run dev

# Compile
npm run build

# Start compiled server
npm start

# Open MCP Inspector
npm run inspector

Project layout

src/
├── index.ts                 # process entry point
├── server.ts                # MCP server and tool registration
├── handlers/                # request handlers
├── tools/                   # filesystem, edit, process, PDF and other tools
├── search-manager.ts        # search orchestration
├── terminal-manager.ts      # command/session management
└── utils/
    └── ripgrep-resolver.ts  # cross-platform ripgrep discovery

🌐 Portability notes

For normal use, run npm install on the same OS/architecture where the MCP server will run so native dependencies are installed correctly.

The repository also contains an optional Linux x86-64 ripgrep binary under tools/Linux/rg for custom portable packaging workflows. It is not required for ordinary source installs. See tools/README.md.

🤝 Upstream & attribution

This repository is derived from Desktop Commander MCP by Eduard Ruzga and contributors:

• Upstream: https://github.com/wonderwhy-er/DesktopCommanderMCP

• License: MIT

Portable packaging and ripgrep-resolution adjustments in this fork are maintained separately. Upstream trademarks, services, and release channels are not implied to endorse this fork.

See LICENSE and THIRD_PARTY_NOTICES.md.

📄 License

MIT License. See LICENSE.

Built for developers who want a straightforward, local-first MCP tool server.