run_command
Execute shell commands securely within a controlled Node.js environment using the Model Context Protocol, enabling safe and structured command execution for AI models like Claude.
Instructions
Run a shell command
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | No |
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 ]);