How to Capture a Webpage Screenshot with an AI Agent in Firefox

To capture a webpage screenshot with an AI agent in Firefox, connect the agent to a browser-control layer such as Mozilla’s Firefox DevTools MCP. Ask the agent to navigate to the page, wait until the content you need is visible, and call screenshot_page. For a specific element, identify it from a fresh page snapshot and call screenshot_by_uid. Both tools can save the image to a file with saveTo. This MCP project is pre-1.0 and its tool interface may change, so check the current project documentation when setting it up.

If you need a simple headless capture without an AI agent, Firefox’s command line supports --headless, --screenshot, and --window-size. For a manual capture, Firefox’s built-in screenshot UI supports visible-page, full-page, region, and page-part screenshots.

1. Connect an AI agent to Firefox with MCP

Mozilla’s Firefox DevTools MCP server lets AI assistants inspect and control Firefox through WebDriver BiDi. It exposes page navigation and screenshot tools, among others. The repository documents screenshot_page for a page and screenshot_by_uid for an element identified by a UID.

Install Node.js and make sure Firefox is installed. The server can use the system Firefox or a path you specify.
Register the server with your MCP client. For Claude Code, Mozilla’s documentation gives this command:

claude mcp add firefox-devtools npx @mozilla/firefox-devtools-mcp-moz

For a user-wide Claude Code configuration, add --scope user. Other MCP clients need an equivalent server entry using the package command. Restart the client so it loads the server.

Ask the agent to navigate to the target URL, wait for the page state you need, and capture it. Save the result to a distinct path:

Navigate Firefox to https://example.com.
Wait until the main content is visible, then call screenshot_page with saveTo set to "artifacts/example-homepage.png".

The prompt describes the workflow; the exact tool-call syntax depends on the MCP client. The MCP documentation says screenshot tools accept saveTo, which can be a file path, an existing directory, or true for a generated path. Relative paths use the current working directory; by default, absolute paths are restricted to the MCP output directory. See the current project README for its path rules and setup details.

Capture one element

Ask the agent to take a fresh page snapshot, find the target element’s UID, and call screenshot_by_uid with that UID. UIDs can become stale after navigation or when an element is removed, so take a new snapshot if the tool says the UID no longer exists.

Take a fresh snapshot of the current page. Find the UID for the main article element and call screenshot_by_uid for that UID, saving it to "artifacts/article.png".

This method depends on the agent and MCP client passing the tool arguments correctly. If the target is ambiguous, ask the agent to identify the element by its visible content or role, then verify the resulting capture.

Set Firefox options when needed

The MCP server accepts options for the Firefox binary, headless mode, viewport, profile, startup URL, certificates, Firefox arguments, environment variables, and output logging. Start with defaults, then add only options your workflow needs.

Option	Use
`--firefox-path <path>`	Select a particular Firefox executable, such as a local development build.
`--headless`	Run Firefox without a visible UI.
`--viewport 1280x720`	Set the initial browser viewport size.
`--profile-path <path>`	Use a particular Firefox profile directory.
`--start-url <url>`	Choose the initial page; the documented default is `about:home`.
`--accept-insecure-certs`	Ignore TLS certificate errors. Use only when that is appropriate for your environment.
`--firefox-arg <arg>`	Pass an additional argument to Firefox.
`--env KEY=VALUE`	Set an environment variable for Firefox; this option can be repeated.
`--output-file <path>`	Write Firefox output to a file.

For example, a client configuration can pass --headless and a viewport argument when launching the server. Configuration formats differ by client; use the format documented by your MCP client and the current Mozilla project docs.

2. Make the capture reflect the state you want

A screenshot records a moment in the page lifecycle. Before calling the capture tool, tell the agent what state matters: for example, the page’s main content is visible, a particular section has loaded, or a menu is open. Waiting for that state is workflow guidance, not a guarantee that every page has finished loading. Pages may continue rendering after navigation because of client-side code, delayed images, animations, or user interaction.

For a page screenshot: use screenshot_page after the target page is selected and ready.
For an element screenshot: take a current snapshot, find the element UID, then use screenshot_by_uid.
For repeated captures: use a unique filename or a timestamped output directory so earlier images are preserved.
For a fixed viewport: set the MCP viewport option or use --viewport before capture.

The Firefox DevTools MCP project is under active development. Check its current tool names and compatibility if an example in your client no longer matches the installed server.

3. Use Firefox’s headless command line for a simple capture

If the job is just to open a URL and write a screenshot, you can skip MCP and invoke Firefox directly. This is useful in scripts and build jobs where an AI agent does not need to inspect or interact with the page.

firefox --headless --screenshot /tmp/page.png --window-size 1280,900 https://example.com

Adjust the URL, output path, and dimensions for your use case. Firefox documents --screenshot as implying headless mode, so --headless is optional in this exact command. The headless option is documented for Windows, Linux GTK, and macOS; command availability can differ across builds and platforms. The window-size argument takes a width and optionally a height.

4. Capture manually with Firefox

For a human-operated screenshot, right-click an empty part of the page and choose Take Screenshot, or use Ctrl+Shift+S on Windows and Linux, or Command+Shift+S on macOS. Choose visible page, full page, a selected region, or an automatically highlighted page part, then save or copy the image.

For a developer-directed full-page or element capture, Firefox DevTools also provides screenshot controls. Enable the screenshot toolbar button in DevTools settings to capture the full page. To capture an element, use the Inspector’s HTML pane context menu and choose Screenshot Node.

Use the Web Console screenshot helper

Firefox’s Web Console provides a :screenshot helper with options for capture scope and output. Examples:

:screenshot --fullpage --filename=page.png
:screenshot --selector="main article" --filename=article.png
:screenshot --delay=1.5 --dpr=2 --filename=menu-state.png

Option	Effect
`--fullpage`	Capture the full webpage, including parts outside the current window bounds.
`--selector`	Capture one element selected by CSS selector, including its descendants.
`--delay`	Wait the specified number of seconds before capture; useful for a menu or hover state.
`--dpr`	Set device-pixel ratio. Values above 1 produce a more zoomed-in image; values below 1 produce a more zoomed-out image.
`--filename`	Set the output filename; Firefox’s documentation specifies a PNG extension.
`--clipboard`	Copy the screenshot to the clipboard. This prevents file output unless `--file` is also used.
`--file`	Force saving to a file, including when using other output options.

Check the Firefox version’s help or documentation if an option is not recognized. Reusing a filename overwrites the previous image.

5. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its API accepts a URL in one GET request and returns a PNG, JPEG, WebP, or PDF. The example below saves the response as WebP:

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webp

See the ScreenshotNeo API documentation for request options and formats. Cookie banners are accepted like a visitor and more than 60 known consent platforms, newsletter popups, and chat widgets are removed before capture; each step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers say the page verdict and whether the request was billed. Its MCP server gives AI agents the tools take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Start free with 1,000 screenshots a month and no card.

6. Troubleshooting

Symptom	Likely cause	What to try
The MCP server does not appear in the agent.	The client has not loaded the server configuration or has not restarted.	Check the client’s MCP configuration and restart it after registration. Confirm Node.js is available to the server command.
The MCP connection closes during startup on Windows.	Mozilla documents a Windows setup case where `python3` is not on `PATH`.	Start Claude Code from the MozillaBuild shell or configure `MACH_PYTHON` as Mozilla’s docs describe.
Firefox is not found.	The executable is not in the expected location.	Pass `--firefox-path` with the actual Firefox executable path.
An element capture says the UID is stale or missing.	The element was removed or the page navigated after the snapshot.	Take a fresh snapshot and resolve the element again before calling `screenshot_by_uid`.
The screenshot shows a loading state or incomplete content.	The page had not reached the desired state when capture ran.	Ask the agent to wait for a visible target or a known page condition, then capture again. Delayed or interactive content may need additional page-specific steps.
The screenshot file is not where expected.	`saveTo` is relative to the MCP server working directory, or the requested absolute path is outside its allowed locations.	Use a path within the allowed output directory, use a relative path, or review the server’s save-path configuration.
A previous screenshot disappeared.	The new capture used the same filename.	Use a distinct filename per run; Firefox DevTools and MCP file saves can overwrite existing outputs depending on the path.
`firefox --headless` is not recognized.	The Firefox build or platform may not support the option as documented.	Confirm the installed executable and platform; Firefox documents headless support for Windows, Linux GTK, and macOS.
The manual selection crosshair does not move with keys on Wayland.	Firefox Support documents this keyboard limitation.	Use pointer selection or a different capture route.

7. Performance, reliability, and cost considerations

Performance: Capture time depends on Firefox startup, navigation, and page rendering. The MCP project notes that the first run can be slower while the WebDriver BiDi session is set up; later runs are faster. No cross-site benchmark is established here.
Reliability: Use a stable viewport and wait for the page state relevant to your capture. Prefer a fresh element snapshot after navigation. For repeatable automation, use unique output names and record the URL, viewport, and run context alongside each image.
Resource use: Full-page captures and large pages can produce bulky image files and tool output. MCP’s saveTo option keeps screenshot bytes in a file rather than returning them inline to the agent conversation.
Privacy: Mozilla says Firefox Screenshots collects interaction events such as using Copy or Save full page, but not the captured URL or image details. That statement applies to Firefox’s built-in feature and should not be generalized to third-party agents, MCP clients, model providers, or websites.
Cost: Firefox’s built-in and command-line screenshot routes have no per-capture API price described in the cited documentation; infrastructure and development costs depend on your environment. ScreenshotNeo’s listed plan prices are Free for 1,000 shots/month, Starter $5 for 3,000, Growth $15 for 15,000, Pro $39 for 60,000, Scale $99 for 250,000, and Business $249 for 1,000,000. Yearly billing gives two months free; every feature is on every plan.

8. Frequently asked questions

Can the AI agent save the screenshot directly to disk?

Yes. Mozilla’s MCP screenshot tools accept saveTo, including a file path or directory, subject to the server’s save-path restrictions.

Can I capture only a CSS-selected element through Firefox DevTools?

Yes. The Web Console :screenshot helper accepts --selector. In the MCP workflow, select an element from a page snapshot and use its UID with screenshot_by_uid.

Does a full-page screenshot include below-the-fold content?

Firefox’s built-in screenshot interface and DevTools full-page option can capture beyond the visible viewport. For the MCP screenshot tool, consult the current project documentation for the installed version’s exact options.

The cited setup supports a Firefox profile path, but the research does not establish behavior for any specific login flow. Use an appropriate profile and follow your organization’s credential-handling rules.