Shell MCP Server

Instructions

Implementation Reference

• src/index.ts:104-139 (handler)

  The CallToolRequestSchema handler that implements the 'run_command' tool. It extracts the command, validates its existence and safety, executes it using execa in shell mode, and returns stdout/stderr or error content.

  this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
    if (request.params.name !== 'run_command') {
      throw new Error(`Unknown tool: ${request.params.name}`);
    }
  
    const command = request.params.arguments?.command as string;
    try {
      const baseCommand = command.trim().split(/\s+/)[0];
      if (!(await commandExists(baseCommand))) {
        throw new Error(`Command not found: ${baseCommand}`);
      }
  
      if (!validateCommand(baseCommand)) {
        throw new Error(`Command not allowed: ${baseCommand}`);
      }
  
      const { stdout, stderr } = await execa(command, [], {
        shell: true,
        env: process.env,
      });
  
      return {
        content: [{ type: 'text', text: stdout || stderr, mimeType: 'text/plain' }],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: String(error),
            mimeType: 'text/plain',
          },
        ],
      };
    }
  });

• src/index.ts:94-99 (schema)

  Input schema definition for the 'run_command' tool, specifying an object with a required 'command' string property.

  inputSchema: {
    type: 'object',
    properties: {
      command: { type: 'string' },
    },
  },

• src/index.ts:89-102 (registration)

  Registration of the 'run_command' tool via the ListToolsRequestSchema handler, including name, description, and input schema.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
    tools: [
      {
        name: 'run_command',
        description: 'Run a shell command',
        inputSchema: {
          type: 'object',
          properties: {
            command: { type: 'string' },
          },
        },
      },
    ],
  }));

• src/index.ts:53-55 (helper)

  Helper function used by the handler to check if a command's base name is blacklisted.

  function validateCommand(baseCommand: string): boolean {
    return !BLACKLISTED_COMMANDS.has(baseCommand);
  }

• src/index.ts:16-50 (helper)

  Set of blacklisted dangerous commands that the 'run_command' tool refuses to execute for security.

  const BLACKLISTED_COMMANDS = new Set([
    // File System Destruction Commands
    'rm', // Remove files/directories - Could delete critical system or user files
    'rmdir', // Remove directories - Could delete important directories
    'del', // Windows delete command - Same risks as rm
  
    // Disk/Filesystem Commands
    'format', // Formats entire disks/partitions - Could destroy all data on drives
    'mkfs', // Make filesystem - Could reformat drives and destroy data
    'dd', // Direct disk access - Can overwrite raw disks, often called "disk destroyer"
  
    // Permission/Ownership Commands
    'chmod', // Change file permissions - Could make critical files accessible or inaccessible
    'chown', // Change file ownership - Could transfer ownership of sensitive files
  
    // Privilege Escalation Commands
    'sudo', // Superuser do - Allows running commands with elevated privileges
    'su', // Switch user - Could be used to gain unauthorized user access
  
    // Code Execution Commands
    'exec', // Execute commands - Could run arbitrary commands with shell's privileges
    'eval', // Evaluate strings as code - Could execute malicious code injection
  
    // System Communication Commands
    'write', // Write to other users' terminals - Could be used for harassment/phishing
    'wall', // Write to all users - Could be used for system-wide harassment
  
    // System Control Commands
    'shutdown', // Shut down the system - Denial of service
    'reboot', // Restart the system - Denial of service
    'init', // System initialization control - Could disrupt system state
  
    // Additional High-Risk Commands
    'mkfs', // Duplicate of above, filesystem creation - Data destruction risk
  ]);