shell_execute

Instructions

Implementation Reference

• src/tools/shell.ts:39-93 (handler)

  Core handler function that executes the shell command using Node.js child_process.exec (promisified), supports sudo by wrapping in sudo bash -c, handles environment, cwd, timeout, captures stdout/stderr even on error, and returns JSON-formatted response with success status, output, and exit code.

  export async function executeCommand(args: z.infer<typeof executeCommandSchema>): Promise<ToolResponse> {
    try {
      // For sudo commands, wrap the entire command in a shell to ensure all parts run with sudo
      const command = args.sudo
        ? `sudo bash -c ${JSON.stringify(args.command)}`
        : args.command;
      const timeout = args.timeout || 30000;
  
      const { stdout, stderr } = await execAsync(command, {
        cwd: args.cwd,
        env: args.env ? { ...process.env, ...args.env } : process.env,
        shell: args.shell || '/bin/bash',
        timeout: timeout,
        maxBuffer: 10 * 1024 * 1024 // 10MB buffer
      });
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              success: true,
              command: command,
              stdout: stdout,
              stderr: stderr,
              exitCode: 0
            }, null, 2)
          }
        ]
      };
    } catch (error: any) {
      // Even if command fails, return the output
      const command = args.sudo
        ? `sudo bash -c ${JSON.stringify(args.command)}`
        : args.command;
  
      return {
        content: [
          {
            type: "text" as const,
            text: JSON.stringify({
              success: false,
              command: command,
              stdout: error.stdout || '',
              stderr: error.stderr || error.message,
              exitCode: error.code || 1,
              signal: error.signal,
              timedOut: error.killed && error.signal === 'SIGTERM'
            }, null, 2)
          }
        ],
        isError: true
      };
    }
  }

• src/tools/shell.ts:15-22 (schema)

  Zod schema for validating input parameters to the shell_execute tool: command (required), optional cwd, env, timeout, shell, sudo.

  export const executeCommandSchema = z.object({
    command: z.string().describe('The shell command to execute'),
    cwd: z.string().optional().describe('Working directory for the command (defaults to current directory)'),
    env: z.record(z.string()).optional().describe('Environment variables to set for the command'),
    timeout: z.number().optional().describe('Timeout in milliseconds (default: 30000ms)'),
    shell: z.string().optional().describe('Shell to use (default: /bin/bash)'),
    sudo: z.boolean().default(false).describe('Execute with sudo privileges')
  });

• src/tools/shell.ts:177-225 (registration)

  MCP tool registration object defining name 'shell_execute', detailed description of usage, and JSON inputSchema matching the Zod schema. Part of shellTools array exported for use in server.

    {
      name: 'shell_execute',
      description: `Execute a shell command with full system access. Supports sudo for privileged operations.
  
  Use this for:
  - Running system commands (apt, brew, yum, dnf, pacman, etc.)
  - Installing packages and dependencies
  - Managing services (systemctl, service, etc.)
  - File operations via shell utilities
  - Network operations (curl, wget, ssh, scp, etc.)
  - Git operations
  - Docker commands
  - Any other shell command
  
  The command runs in /bin/bash by default. Output is captured and returned after completion.
  For long-running commands, use shell_execute_streaming instead.`,
      inputSchema: {
        type: 'object',
        properties: {
          command: {
            type: 'string',
            description: 'The shell command to execute'
          },
          cwd: {
            type: 'string',
            description: 'Working directory for the command (defaults to current directory)'
          },
          env: {
            type: 'object',
            additionalProperties: { type: 'string' },
            description: 'Environment variables to set for the command'
          },
          timeout: {
            type: 'number',
            description: 'Timeout in milliseconds (default: 30000ms)'
          },
          shell: {
            type: 'string',
            description: 'Shell to use (default: /bin/bash)'
          },
          sudo: {
            type: 'boolean',
            default: false,
            description: 'Execute with sudo privileges. Use this for system-level operations like installing packages.'
          }
        },
        required: ['command']
      }
    },

• src/index.ts:347-350 (registration)

  Dispatch/registration in the main CallToolRequest handler: matches tool name 'shell_execute', validates args with executeCommandSchema, and calls the executeCommand handler function.

  if (name === 'shell_execute') {
    const validated = executeCommandSchema.parse(args);
    return await executeCommand(validated);
  }

• src/index.ts:284-296 (registration)

  Server handler for ListToolsRequest that includes ...shellTools (containing shell_execute definition) in the returned list of available tools.

  this.server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: [
        ...filesystemTools,
        ...shellTools,
        ...dockerTools,
        ...mongodbTools,
        ...redisTools,
        ...gitTools,
        ...processTools,
        ...networkTools
      ]
    };