<div align="center">

# 🖥️ Desktop Commander MCP

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

[![CI](https://github.com/luffy666code/desktop-commander-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/luffy666code/desktop-commander-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-MCP-6f42c1)](https://modelcontextprotocol.io/)

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

**English** · [简体中文](README_zh-CN.md)

</div>

> A community-maintained portable adaptation of [Desktop Commander MCP](https://github.com/wonderwhy-er/DesktopCommanderMCP).  
> It is designed for standard **stdio-compatible MCP clients** and does not depend on any vendor-specific deployment platform.

---

## ✨ Highlights

| Capability | What it gives your AI client |
|---|---|
| 📁 Filesystem | Read, write, move, list, search, and inspect files and directories |
| 🔎 Fast search | Recursive content search powered by ripgrep |
| 💻 Terminal | Run shell commands, stream output, and handle long-running processes |
| ⚙️ Process control | List, inspect, and terminate processes |
| 📝 Editing | Targeted text replacement and larger file rewrites |
| 📊 Documents | Excel, PDF, DOCX, Markdown, text, and binary-aware file handling |
| 🧰 Configuration | Runtime configuration plus a conservative default command blocklist |
| 🌍 Cross-platform | Windows, Linux, and macOS source installs with runtime ripgrep resolution |

## 🚀 Quick start

### 1. Clone

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

### 2. Install and build

```bash
npm install
npm run build
```

Requirements: **Node.js 18+** and npm.

### 3. Verify the search engine

```bash
npm run verify:rg
```

### 4. Add it to your MCP client

Use the standard stdio configuration pattern:

```json
{
  "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](docs/CLIENT_SETUP.md)** for Windows path examples and Inspector usage.

## 🧭 How it works

```text
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.

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

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

## 🛠️ Development

```bash
# 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

```text
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](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](LICENSE) and [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

## 📄 License

MIT License. See [LICENSE](LICENSE).

---

<div align="center">

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

</div>