ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Run a Website Screenshot MCP Server Locally

Run a screenshot MCP server from an MCP client, verify its tools, and choose between a hosted capture service and local Firefox automation.

By the ScreenshotNeo team4 October 20268 min read

To run a website screenshot MCP server locally, configure your MCP client to launch a server process using the transport that server supports. For a documented screenshot-focused setup, Screenshot Scout’s npm package runs as a local stdio process: configure npx -y @screenshotscout/mcp and provide its access key. The process runs on your machine, but captures use your Screenshot Scout account quota and rate limits; this is not an offline browser capture engine. [Screenshot Scout MCP documentation]

If you need the browser itself to be local, Mozilla’s Firefox DevTools MCP is a separate option. It automates a local Firefox installation and includes a screenshot_page tool alongside broader browser debugging and inspection tools. These two approaches have different prerequisites and capabilities.

1. Choose what “locally” means

Approach What runs locally Capture dependency Best fit
Screenshot Scout MCP The MCP server process, launched by your client Screenshot Scout account, quota, and rate limits A dedicated screenshot tool with minimal browser setup
Firefox DevTools MCP The MCP server and Firefox browser Local Firefox installation; network access may still be needed for the target site Screenshot capture as part of broader browser automation and debugging
ScreenshotNeo API or MCP server Your client process; ScreenshotNeo provides the screenshot service, and an MCP server for AI agents ScreenshotNeo account and plan One-call screenshots, clean captures, or agent workflows without configuring a browser

“Local MCP server” usually describes where the MCP process starts, not necessarily where the screenshot is rendered. Check the project’s documentation for capture location, credentials, quota, and transport before treating a setup as offline or local-browser-only.

2. Run Screenshot Scout’s screenshot MCP server

Prerequisites

  • Node.js 22 or newer.
  • An MCP client that supports launching a local server over stdio.
  • A Screenshot Scout account and access key.
  • A secret key as well, only if signed requests are enabled for the access key.

Configure the MCP client

Add a server entry to your client’s MCP configuration. The exact file location varies by client; use its current documentation. The important values are the executable, arguments, and environment variables:

{
  "mcpServers": {
    "screenshot-scout": {
      "command": "npx",
      "args": ["-y", "@screenshotscout/mcp"],
      "env": {
        "SCREENSHOTSCOUT_ACCESS_KEY": "YOUR_ACCESS_KEY"
      }
    }
  }
}

If signed requests are enabled for your key, add the corresponding secret:

"SCREENSHOTSCOUT_SECRET_KEY": "YOUR_SECRET_KEY"

Keep real credentials in a secure environment or secret manager where your MCP client supports one. Do not commit populated configuration files to a repository or paste keys into prompts. The server’s documented tool is capture_screenshot.

Start and invoke it

  1. Save the configuration in the client’s MCP server configuration file.
  2. Restart or reload the client so it launches the configured process.
  3. Open the client’s tool list and check that capture_screenshot is available.
  4. Ask the agent to capture a public test page and inspect the returned image or result.

The client starts the process using the configured command. You generally do not start a separate HTTP server or provide a localhost URL for this stdio setup. Captures run against your Screenshot Scout account and use its quota and rate limits.

3. Verify the MCP connection with Inspector

MCP Inspector provides a visual way to connect to a server, discover its tools, and try tool calls. For a stdio server, configure Inspector to launch the same command and arguments as the MCP client, with the same required environment variables. Then check that the server starts, that capture_screenshot appears, and that a valid test request returns a result. [MCP Inspector documentation]

Match the Inspector transport to the server transport. Screenshot Scout’s npm configuration above is a local process setup. An HTTP MCP server may instead expose an HTTP endpoint; do not copy a localhost /mcp URL from an HTTP example into a stdio configuration. OpenAI’s Inspector quickstart, for example, demonstrates Streamable HTTP for a different server setup. [OpenAI MCP guide]

4. Use local Firefox for browser-based capture

For a local-browser route, Mozilla’s Firefox DevTools MCP repository documents a server that requires Node.js 20.19.0 or newer and Firefox 100 or newer. It includes screenshot_page plus tools for navigating pages, inspecting content, and accessing browser debugging data. This is browser automation with screenshot capability, rather than a dedicated one-tool screenshot service. [Mozilla Firefox DevTools MCP repository]

The repository gives this Codex CLI example:

codex mcp add firefox-devtools -- npx @mozilla/firefox-devtools-mcp@latest

Its Claude Code example is:

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

Consult the repository and your client’s current setup instructions for optional headless and viewport flags. After adding the server, reload the MCP client and confirm that screenshot_page is available. Keep in mind that using a local Firefox installation does not by itself establish that every network interaction or resulting piece of data remains local.

5. Keep browser access scoped

Mozilla warns users to use a dedicated Firefox profile, because an agent with browser access may reach cookies and saved sessions in the profile. Its guidance also recommends caution with sites whose content could attempt prompt injection and enabling only the tool modules needed. These precautions matter especially for a server that can navigate and inspect pages, not just capture a single screenshot. [Mozilla Firefox DevTools MCP security guidance]

  • Create a separate browser profile without personal logins or saved credentials.
  • Limit enabled tools to those needed for the task.
  • Use a test page before giving an agent access to sensitive sites.
  • Do not treat page content as trusted instructions for the agent.

6. Troubleshoot common setup failures

Symptom Likely cause What to check
Server does not appear in the client Invalid configuration, client has not reloaded, or command cannot start Check JSON syntax, command and argument spelling, client logs, and whether the configured Node.js version is available to the client process.
npx or package launch fails Node.js is below the package’s required version, npm cannot fetch the package, or network access is blocked Check node --version, npm availability, and network access to the package registry. Screenshot Scout’s package requires Node.js 22 or newer.
Authentication or authorization error Missing, misspelled, expired, or incorrectly scoped credential Confirm SCREENSHOTSCOUT_ACCESS_KEY is present in the MCP process environment and belongs to the intended account.
Signed request fails Signed requests are enabled but the secret is missing or incorrect Set SCREENSHOTSCOUT_SECRET_KEY to the matching secret when signing is enabled; otherwise do not add it unnecessarily.
Tool is visible but invocation fails validation Request parameters do not match the tool schema or a required field is missing Inspect the tool’s input schema in the client or Inspector and retry with the required fields and valid types.
Inspector cannot connect Inspector transport does not match the server, or process startup failed For stdio, configure Inspector to launch the process with its command, arguments, and environment. For HTTP, use the server’s documented endpoint and ensure the process and port are active.
Firefox server starts but browser operations fail Firefox is missing or below the documented version, or the expected profile/browser setup is unavailable Confirm Firefox 100 or newer is installed and use the repository’s setup instructions. Use a dedicated profile.
Screenshot differs from what a person sees Page timing, authentication state, viewport, dynamic content, or browser context differs Check the tool options, wait for the page to settle, and use a controlled test page and profile. A screenshot server cannot make inaccessible or session-dependent content public.

MCP setup troubleshooting guidance also recommends checking that the process and expected port are active, dependencies are installed, credentials are valid, and tool parameters match the schema. For stdio servers, focus first on process launch and environment variables; port checks apply to servers that actually use a network transport. [Microsoft MCP beginner guide]

7. Performance, reliability, and cost

  • Startup: launching through npx may require fetching the package if it is not cached. A failed first launch can be a package or network issue rather than an MCP protocol issue.
  • Capture time: the target page’s load behavior, scripts, and network conditions affect completion. Browser automation offers control over a local browser but adds browser setup and lifecycle considerations.
  • Reliability: validate the process launch and tool schema independently from target-page behavior. A working MCP connection does not guarantee that every website will load or permit capture.
  • Quota and rate limits: Screenshot Scout says its captures use the user’s account quota and rate limits. Check its current plan details before building a high-volume workflow.
  • Local compute: a local Firefox route uses local browser resources. Keep browser versions and profiles controlled for repeatable agent workflows.

8. Which setup should you use?

Need Suitable starting point
A screenshot tool exposed to an MCP client, with minimal local browser setup Screenshot Scout’s local npm MCP process; account quota and rate limits apply.
Screenshot capture alongside local browser navigation and debugging Mozilla Firefox DevTools MCP with a dedicated Firefox profile.
Clean screenshots through a single HTTP request or an MCP server for AI agents ScreenshotNeo, a website screenshot API and MCP server.

Or skip the browser setup

Use ScreenshotNeo’s screenshot API with one GET request. The following example saves a WebP screenshot of Stripe; replace the target URL and provide your API key. See the ScreenshotNeo API documentation for options.

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

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)
const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await Bun.write('shot.webp', res);

ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and the free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Try it by signing up for free.

FAQ

Does “local MCP server” mean the screenshots stay on my computer?

No general rule guarantees that. Check where the particular server performs capture and where it sends requests or results. Screenshot Scout documents that its captures use its account service; Mozilla’s server requires local Firefox, but that alone does not prove every part of the workflow stays local.

Can I use an HTTP MCP configuration for a stdio server?

No. Configure the transport the server implements. A stdio server is launched as a process by the client; an HTTP server uses a documented endpoint.

Is Firefox DevTools MCP only for screenshots?

No. It also exposes browser navigation, inspection, and debugging capabilities, so scope its enabled tools and profile carefully.

Do I need the Screenshot Scout secret key?

Only when signed requests are enabled for the access key. The access key is required for its documented account-connected setup.

Can I use a local-browser MCP server without an MCP client?

The setup described here is for clients that speak MCP. For direct browser automation without MCP, use the browser automation project’s own documented interface.

Keep reading