What Is the Command Blocklist in Desktop Commander MCP and How to Customize It

The command blocklist is a configurable safety mechanism that prevents Desktop Commander MCP from executing any shell command matching user-defined patterns, even when explicitly requested by AI prompts.

Desktop Commander MCP implements robust execution controls to prevent accidental system damage. The command blocklist serves as your primary defense against destructive operations by intercepting commands before they reach the shell. This feature is fully customizable through the application's configuration system and takes effect immediately on startup.

Where the Command Blocklist Is Defined

The blocklist schema is declared in src/config-field-definitions.ts at line 13, where it is described as "your personal safety blocklist". This configuration field expects an array of strings, with each string representing a command or pattern that should be prohibited from execution.

The actual blocklist values are stored in the user-editable config.json file located in the application root. Because this file is separate from the source code, you can version control your safety settings or sync them across multiple machines without modifying the core application logic.

How the Blocklist Enforcement Works

When a command is submitted for execution, the CommandManager class validates it against the active configuration before spawning any process. In src/command-manager.ts at line 58, the system performs a pattern match check to determine if the command string appears in the blocklist array.

The enforcement logic specifically accounts for command substitution attacks by detecting $() syntax inside quotes, closing a known bypass vector that could otherwise circumvent the safety controls. If the command matches any entry in the blocklist, the manager immediately throws an error with the message "Command is blocked by safety blocklist" and aborts the operation.

Customizing Your Command Blocklist

Editing config.json Directly

Since the blocklist resides in config.json, you can modify it with any text editor. The field accepts exact strings or patterns that will be matched against the full command string:

{
  "blocklist": [
    "rm -rf /",
    "mkfs.*",
    "sudo",
    "curl",
    "wget"
  ]
}

Changes are read on startup and applied immediately, so the blocklist is always synchronized with the latest configuration.

Using the Config Editor UI

Desktop Commander MCP provides a Config Editor interface that surfaces the blocklist field for users who prefer graphical management. This UI writes directly to config.json while validating that your entries conform to the expected array structure defined in the schema.

Programmatic Updates

For automated tooling or custom workflows, you can manipulate the blocklist using the configuration API exposed in tools/config.js:

import { readConfig, writeConfig } from './tools/config.js';

async function addToBlocklist(commandPattern) {
  const cfg = await readConfig();
  cfg.blocklist = cfg.blocklist || [];
  if (!cfg.blocklist.includes(commandPattern)) {
    cfg.blocklist.push(commandPattern);
    await writeConfig(cfg);
    console.log(`Added "${commandPattern}" to the blocklist.`);
  }
}

addToBlocklist('ffmpeg');

Practical Configuration Examples

Basic Safety Configuration

Prevent destructive filesystem operations and unauthorized privilege escalation:

{
  "blocklist": [
    "rm -rf /",
    "mkfs.*",
    "sudo",
    "su"
  ]
}

Network Restriction Pattern

Disallow bandwidth-heavy utilities in constrained environments:

{
  "blocklist": [
    "curl",
    "wget",
    "scp.*",
    "rsync.*"
  ]
}

Verifying Blocklist Enforcement

Test that your restrictions are working correctly by attempting to run a blocked command:

import { CommandManager } from './command-manager.js';

async function testBlocklist() {
  try {
    await CommandManager.run('sudo echo hello');
  } catch (e) {
    console.log(e.message); // → "Command is blocked by safety blocklist"
  }
}

testBlocklist();

Summary

• The command blocklist in src/config-field-definitions.ts defines a user-configurable array of prohibited command patterns stored in config.json
• Enforcement occurs in src/command-manager.ts at line 58, which validates commands before execution and handles $() substitution bypass attempts
• Customization is immediate and requires no restart—edit config.json directly, use the Config Editor UI, or call writeConfig() programmatically
• The blocklist supports pattern matching, allowing you to block command families like mkfs.* or scp.*

Frequently Asked Questions

What happens if a blocked command is attempted?

When the CommandManager detects a blocked command, it throws an error with the message "Command is blocked by safety blocklist" and aborts execution before any shell process is spawned. This prevents both accidental execution and deliberate attempts to run dangerous operations via AI prompts.

Can I use wildcards or regex in the blocklist?

Yes, the blocklist supports pattern matching syntax. According to the implementation in src/command-manager.ts, entries like mkfs.* will match any command starting with "mkfs", allowing you to block entire command families without listing every variant explicitly.

Where is the command blocklist stored?

The blocklist is stored in the config.json file in your Desktop Commander MCP installation directory. This file is user-editable and separate from the application source code, making it safe to customize without affecting the core application.

Does the blocklist require a restart to take effect?

No, changes to the blocklist are read on startup and applied immediately during the configuration loading phase. However, any commands already queued or running when you modify the configuration will complete, as the check occurs at the moment CommandManager receives a new execution request.

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