DesktopCommander MCP Server: AI File Management & SSH

Overview

DesktopCommander MCP Server provides a secure, developer-friendly backend that exposes local file and shell capabilities to AI agents using the Model Context Protocol (MCP). It lets an assistant read and write files, execute terminal commands, and open SSH sessions to remote hosts while enforcing configuration, logging, and access controls. This is useful when you want an AI agent to perform real work on a development machine, CI runner, or remote server without giving it full interactive access.

Because the server implements a constrained set of tools and runs as a standalone service, you can colocate it with your projects, restrict which directories and commands are available, and integrate it with existing agent frameworks. The project source and issues are on GitHub: https://github.com/wonderwhy-er/DesktopCommanderMCP

Features

• File management: list, read, write, create, and delete files and directories
• Terminal execution: run shell commands with timeout and sandboxing options
• SSH client: connect to remote hosts using configured keys and run remote commands
• Authentication & allowlists: restrict access via API keys and path whitelist
• Audit logging: record executed commands and file operations for traceability
• Lightweight HTTP server compatible with MCP-based agent clients
• Docker-friendly deployment and environment-driven configuration

Installation / Configuration

Clone the repository and run with Python (recommended) or Docker.

Quick start (Python virtualenv):

git clone https://github.com/wonderwhy-er/DesktopCommanderMCP.git
cd DesktopCommanderMCP

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# copy example env and edit
cp .env.example .env
# edit .env to set API_KEY, UPLOAD_DIR, SSH_PRIVATE_KEY_PATH, etc.

# run the server (UVicorn example)
uvicorn desktopcommander.server:app --host 0.0.0.0 --port 8080

Docker build + run:

docker build -t desktopcommander-mcp .
docker run -d --name desktopcommander \
  -p 8080:8080 \
  -v /path/to/data:/data \
  --env-file .env \
  desktopcommander-mcp

Example .env (edit to your environment):

API_KEY=replace-with-a-secure-token
PORT=8080
UPLOAD_DIR=/data
ALLOWED_PATHS=/data,/home/dev/projects
SSH_PRIVATE_KEY_PATH=/secrets/id_rsa
COMMAND_TIMEOUT=30
LOG_LEVEL=info

Recommended systemd unit (example):

[Unit]
Description=DesktopCommander MCP Server
After=network.target

[Service]
User=desktopcommander
WorkingDirectory=/opt/DesktopCommanderMCP
ExecStart=/opt/DesktopCommanderMCP/venv/bin/uvicorn desktopcommander.server:app --host 0.0.0.0 --port 8080
EnvironmentFile=/opt/DesktopCommanderMCP/.env
Restart=on-failure

[Install]
WantedBy=multi-user.target

Available Tools / Resources

Below are the primary MCP tools the server exposes to clients (tool names are conceptual; client libraries map these into MCP tool calls).

Clients typically authenticate with an API key and call only the tools granted by server-side configuration.

Use Cases

• Local development assistant: Let an AI agent refactor files, run tests, and open a PR by reading/writing project files and executing build/test commands.

  • Example: agent calls files.read to open a file, modifies content, calls files.write, then runs terminal.exec to run unit tests.

• Remote maintenance via SSH: Use the server as a controlled gateway for scripted maintenance on remote hosts using stored SSH keys.

  • Example: run a remote upgrade with ssh.exec “sudo apt update && sudo apt upgrade -y” after verifying allowed commands.

• CI orchestration and automated debugging: Attach an agent to CI logs and allow it to run investigative commands (e.g., grep logs, collect system info) without exposing full shell access to the CI environment.

• Data extraction and transformation: Upload datasets, let the agent run analysis scripts, and retrieve processed results using the files.* tools.

Security & Best Practices

• Run DesktopCommander