SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:154-203 (handler)

  The main execution logic for the ssh_exec tool. It validates the private key path, escapes the command for safe execution, constructs an SSH command using bash -ic to load the remote shell environment, and runs it via child_process.exec with error handling and logging.

  case 'ssh_exec': {
      const args = request.params.arguments as {
          host: string;
          command: string;
          username: string;
          privateKeyPath: string;
      };
      const { host, command, username, privateKeyPath } = args;
  
      try {
          const validatedKeyPath = validatePrivateKeyPath(privateKeyPath);
          // Escape single quotes in the command for bash -ic
          const escapedCommand = command.replace(/'/g, "'\\''");
          // Wrap the command in bash -ic '...' to load shell environment
          const sshCommand = `ssh -i "${validatedKeyPath}" ${username}@${host} "bash -ic '${escapedCommand}'"`;
          console.error('Executing SSH command:', sshCommand); // Log the modified command
  
          return new Promise((resolve) => {
              // Increased maxBuffer size for potentially larger output from env loading
              exec(sshCommand, { maxBuffer: 1024 * 1024 * 5 }, (error, stdout, stderr) => {
                  if (error) {
                      // Log both stdout and stderr on error for better debugging
                      console.error(`SSH error: ${error.message}`);
                      console.error(`SSH stderr: ${stderr}`);
                      console.error(`SSH stdout (partial): ${stdout}`);
                      resolve({
                          content: [{
                              type: 'text',
                              text: `SSH command failed.\nError: ${error.message}\nstderr: ${stderr}\nstdout: ${stdout}`,
                          }],
                          isError: true,
                      });
                  } else {
                      console.log(`SSH success: ${stdout}`);
                      resolve({
                          content: [{
                              type: 'text',
                              text: stdout,
                          }],
                      });
                  }
              });
          });
      } catch (error: unknown) {
          return {
              content: [{ type: 'text', text: `Error preparing SSH command: ${error instanceof Error ? error.message : String(error)}` }],
              isError: true,
          };
      }
  }

• src/index.ts:83-96 (registration)

  Registration of the 'ssh_exec' tool in the ListToolsRequestSchema handler, including the tool name, description, and input schema definition.

  {
      name: 'ssh_exec',
      description: 'Execute command over SSH using private key file path',
      inputSchema: {
          type: 'object',
          properties: {
              host: { type: 'string' },
              command: { type: 'string' },
              username: { type: 'string' },
              privateKeyPath: { type: 'string' },
          },
          required: ['host', 'command', 'username', 'privateKeyPath'],
      },
  },

• src/index.ts:49-60 (helper)

  Supporting helper function used by ssh_exec to validate the existence and resolve the absolute path of the SSH private key file.

  function validatePrivateKeyPath(path: string): string {
      console.error('DEBUG: Validating key path input:', path); // Log input
      if (typeof path !== 'string') {
          throw new Error('validatePrivateKeyPath received non-string input');
      }
      const resolvedPath = resolve(path);
      console.error('DEBUG: Resolved key path:', resolvedPath); // Log resolved
      if (!existsSync(resolvedPath)) {
          throw new Error(`Private key file not found at path: ${resolvedPath}`);
      }
      return resolvedPath;
  }