BrowserTools MCP

Instructions

Implementation Reference

• browser-tools-mcp/mcp-server.ts:251-299 (handler)

  MCP tool handler for 'takeScreenshot': registers the tool and implements the logic by sending a POST request to the browser connector server's /capture-screenshot endpoint, returning success or error message.

  server.tool(
    "takeScreenshot",
    "Take a screenshot of the current browser tab",
    async () => {
      return await withServerConnection(async () => {
        try {
          const response = await fetch(
            `http://${discoveredHost}:${discoveredPort}/capture-screenshot`,
            {
              method: "POST",
            }
          );
  
          const result = await response.json();
  
          if (response.ok) {
            return {
              content: [
                {
                  type: "text",
                  text: "Successfully saved screenshot",
                },
              ],
            };
          } else {
            return {
              content: [
                {
                  type: "text",
                  text: `Error taking screenshot: ${result.error}`,
                },
              ],
            };
          }
        } catch (error: any) {
          const errorMessage =
            error instanceof Error ? error.message : String(error);
          return {
            content: [
              {
                type: "text",
                text: `Failed to take screenshot: ${errorMessage}`,
              },
            ],
          };
        }
      });
    }
  );

• browser-tools-server/browser-connector.ts:940-1249 (handler)

  Server-side HTTP POST /capture-screenshot handler: sends 'take-screenshot' WebSocket message to Chrome extension, waits for base64 PNG data response, saves to file in configured path (default Downloads/mcp-screenshots), optionally auto-pastes into Cursor on macOS.

  async captureScreenshot(req: express.Request, res: express.Response) {
    console.log("Browser Connector: Starting captureScreenshot method");
    console.log("Browser Connector: Request headers:", req.headers);
    console.log("Browser Connector: Request method:", req.method);
  
    if (!this.activeConnection) {
      console.log(
        "Browser Connector: No active WebSocket connection to Chrome extension"
      );
      return res.status(503).json({ error: "Chrome extension not connected" });
    }
  
    try {
      console.log("Browser Connector: Starting screenshot capture...");
      const requestId = Date.now().toString();
      console.log("Browser Connector: Generated requestId:", requestId);
  
      // Create promise that will resolve when we get the screenshot data
      const screenshotPromise = new Promise<{
        data: string;
        path?: string;
        autoPaste?: boolean;
      }>((resolve, reject) => {
        console.log(
          `Browser Connector: Setting up screenshot callback for requestId: ${requestId}`
        );
        // Store callback in map
        screenshotCallbacks.set(requestId, { resolve, reject });
        console.log(
          "Browser Connector: Current callbacks:",
          Array.from(screenshotCallbacks.keys())
        );
  
        // Set timeout to clean up if we don't get a response
        setTimeout(() => {
          if (screenshotCallbacks.has(requestId)) {
            console.log(
              `Browser Connector: Screenshot capture timed out for requestId: ${requestId}`
            );
            screenshotCallbacks.delete(requestId);
            reject(
              new Error(
                "Screenshot capture timed out - no response from Chrome extension"
              )
            );
          }
        }, 10000);
      });
  
      // Send screenshot request to extension
      const message = JSON.stringify({
        type: "take-screenshot",
        requestId: requestId,
      });
      console.log(
        `Browser Connector: Sending WebSocket message to extension:`,
        message
      );
      this.activeConnection.send(message);
  
      // Wait for screenshot data
      console.log("Browser Connector: Waiting for screenshot data...");
      const {
        data: base64Data,
        path: customPath,
        autoPaste,
      } = await screenshotPromise;
      console.log("Browser Connector: Received screenshot data, saving...");
      console.log("Browser Connector: Custom path from extension:", customPath);
      console.log("Browser Connector: Auto-paste setting:", autoPaste);
  
      // Always prioritize the path from the Chrome extension
      let targetPath = customPath;
  
      // If no path provided by extension, fall back to defaults
      if (!targetPath) {
        targetPath =
          currentSettings.screenshotPath || getDefaultDownloadsFolder();
      }
  
      // Convert the path for the current platform
      targetPath = convertPathForCurrentPlatform(targetPath);
  
      console.log(`Browser Connector: Using path: ${targetPath}`);
  
      if (!base64Data) {
        throw new Error("No screenshot data received from Chrome extension");
      }
  
      try {
        fs.mkdirSync(targetPath, { recursive: true });
        console.log(`Browser Connector: Created directory: ${targetPath}`);
      } catch (err) {
        console.error(
          `Browser Connector: Error creating directory: ${targetPath}`,
          err
        );
        throw new Error(
          `Failed to create screenshot directory: ${
            err instanceof Error ? err.message : String(err)
          }`
        );
      }
  
      const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
      const filename = `screenshot-${timestamp}.png`;
      const fullPath = path.join(targetPath, filename);
      console.log(`Browser Connector: Full screenshot path: ${fullPath}`);
  
      // Remove the data:image/png;base64, prefix if present
      const cleanBase64 = base64Data.replace(/^data:image\/png;base64,/, "");
  
      // Save the file
      try {
        fs.writeFileSync(fullPath, cleanBase64, "base64");
        console.log(`Browser Connector: Screenshot saved to: ${fullPath}`);
      } catch (err) {
        console.error(
          `Browser Connector: Error saving screenshot to: ${fullPath}`,
          err
        );
        throw new Error(
          `Failed to save screenshot: ${
            err instanceof Error ? err.message : String(err)
          }`
        );
      }
  
      // Check if running on macOS before executing AppleScript
      if (os.platform() === "darwin" && autoPaste === true) {
        console.log(
          "Browser Connector: Running on macOS with auto-paste enabled, executing AppleScript to paste into Cursor"
        );
  
        // Create the AppleScript to copy the image to clipboard and paste into Cursor
        // This version is more robust and includes debugging
        const appleScript = `
          -- Set path to the screenshot
          set imagePath to "${fullPath}"
          
          -- Copy the image to clipboard
          try
            set the clipboard to (read (POSIX file imagePath) as «class PNGf»)
          on error errMsg
            log "Error copying image to clipboard: " & errMsg
            return "Failed to copy image to clipboard: " & errMsg
          end try
          
          -- Activate Cursor application
          try
            tell application "Cursor"
              activate
            end tell
          on error errMsg
            log "Error activating Cursor: " & errMsg
            return "Failed to activate Cursor: " & errMsg
          end try
          
          -- Wait for the application to fully activate
          delay 3
          
          -- Try to interact with Cursor
          try
            tell application "System Events"
              tell process "Cursor"
                -- Get the frontmost window
                if (count of windows) is 0 then
                  return "No windows found in Cursor"
                end if
                
                set cursorWindow to window 1
                
                -- Try Method 1: Look for elements of class "Text Area"
                set foundElements to {}
                
                -- Try different selectors to find the text input area
                try
                  -- Try with class
                  set textAreas to UI elements of cursorWindow whose class is "Text Area"
                  if (count of textAreas) > 0 then
                    set foundElements to textAreas
                  end if
                end try
                
                if (count of foundElements) is 0 then
                  try
                    -- Try with AXTextField role
                    set textFields to UI elements of cursorWindow whose role is "AXTextField"
                    if (count of textFields) > 0 then
                      set foundElements to textFields
                    end if
                  end try
                end if
                
                if (count of foundElements) is 0 then
                  try
                    -- Try with AXTextArea role in nested elements
                    set allElements to UI elements of cursorWindow
                    repeat with anElement in allElements
                      try
                        set childElements to UI elements of anElement
                        repeat with aChild in childElements
                          try
                            if role of aChild is "AXTextArea" or role of aChild is "AXTextField" then
                              set end of foundElements to aChild
                            end if
                          end try
                        end repeat
                      end try
                    end repeat
                  end try
                end if
                
                -- If no elements found with specific attributes, try a broader approach
                if (count of foundElements) is 0 then
                  -- Just try to use the Command+V shortcut on the active window
                   -- This assumes Cursor already has focus on the right element
                    keystroke "v" using command down
                    delay 1
                    keystroke "here is the screenshot"
                    delay 1
                   -- Try multiple methods to press Enter
                   key code 36 -- Use key code for Return key
                   delay 0.5
                   keystroke return -- Use keystroke return as alternative
                   return "Used fallback method: Command+V on active window"
                else
                  -- We found a potential text input element
                  set inputElement to item 1 of foundElements
                  
                  -- Try to focus and paste
                  try
                    set focused of inputElement to true
                    delay 0.5
                    
                    -- Paste the image
                    keystroke "v" using command down
                    delay 1
                    
                    -- Type the text
                    keystroke "here is the screenshot"
                    delay 1
                    -- Try multiple methods to press Enter
                    key code 36 -- Use key code for Return key
                    delay 0.5
                    keystroke return -- Use keystroke return as alternative
                    return "Successfully pasted screenshot into Cursor text element"
                  on error errMsg
                    log "Error interacting with found element: " & errMsg
                    -- Fallback to just sending the key commands
                    keystroke "v" using command down
                    delay 1
                    keystroke "here is the screenshot"
                    delay 1
                    -- Try multiple methods to press Enter
                    key code 36 -- Use key code for Return key
                    delay 0.5
                    keystroke return -- Use keystroke return as alternative
                    return "Used fallback after element focus error: " & errMsg
                  end try
                end if
              end tell
            end tell
          on error errMsg
            log "Error in System Events block: " & errMsg
            return "Failed in System Events: " & errMsg
          end try
        `;
  
        // Execute the AppleScript
        exec(`osascript -e '${appleScript}'`, (error, stdout, stderr) => {
          if (error) {
            console.error(
              `Browser Connector: Error executing AppleScript: ${error.message}`
            );
            console.error(`Browser Connector: stderr: ${stderr}`);
            // Don't fail the response; log the error and proceed
          } else {
            console.log(`Browser Connector: AppleScript executed successfully`);
            console.log(`Browser Connector: stdout: ${stdout}`);
          }
        });
      } else {
        if (os.platform() === "darwin" && !autoPaste) {
          console.log(
            `Browser Connector: Running on macOS but auto-paste is disabled, skipping AppleScript execution`
          );
        } else {
          console.log(
            `Browser Connector: Not running on macOS, skipping AppleScript execution`
          );
        }
      }
  
      res.json({
        path: fullPath,
        filename: filename,
      });
    } catch (error) {
      const errorMessage =
        error instanceof Error ? error.message : String(error);
      console.error(
        "Browser Connector: Error capturing screenshot:",
        errorMessage
      );
      res.status(500).json({
        error: errorMessage,
      });
    }
  }

• browser-tools-server/browser-connector.ts:620-632 (registration)

  Express route registration for POST /capture-screenshot endpoint in BrowserConnector constructor.

  this.app.post(
    "/capture-screenshot",
    async (req: express.Request, res: express.Response) => {
      console.log(
        "Browser Connector: Received request to /capture-screenshot endpoint"
      );
      console.log("Browser Connector: Request body:", req.body);
      console.log(
        "Browser Connector: Active WebSocket connection:",
        !!this.activeConnection
      );
      await this.captureScreenshot(req, res);
    }

• chrome-extension/devtools.js:967-1005 (handler)

  Chrome extension WebSocket message handler for 'take-screenshot': invokes chrome.tabs.captureVisibleTab API to capture visible tab as PNG base64 dataUrl, sends back via WS with path and autoPaste settings.

  } else if (message.type === "take-screenshot") {
    console.log("Chrome Extension: Taking screenshot...");
    // Capture screenshot of the current tab
    chrome.tabs.captureVisibleTab(null, { format: "png" }, (dataUrl) => {
      if (chrome.runtime.lastError) {
        console.error(
          "Chrome Extension: Screenshot capture failed:",
          chrome.runtime.lastError
        );
        ws.send(
          JSON.stringify({
            type: "screenshot-error",
            error: chrome.runtime.lastError.message,
            requestId: message.requestId,
          })
        );
        return;
      }
  
      console.log("Chrome Extension: Screenshot captured successfully");
      // Just send the screenshot data, let the server handle paths
      const response = {
        type: "screenshot-data",
        data: dataUrl,
        requestId: message.requestId,
        // Only include path if it's configured in settings
        ...(settings.screenshotPath && { path: settings.screenshotPath }),
        // Include auto-paste setting
        autoPaste: settings.allowAutoPaste,
      };
  
      console.log("Chrome Extension: Sending screenshot data response", {
        ...response,
        data: "[base64 data]",
      });
  
      ws.send(JSON.stringify(response));
    });
  } else if (message.type === "get-current-url") {