ScreenshotNeo
Sign in Get a free key

BlogAI agents

How to Connect a Website Screenshot MCP Server to Cursor

Connect a website screenshot MCP server to Cursor with Microsoft Playwright MCP, configure project or global access, and troubleshoot common setup issues.

By the ScreenshotNeo team4 October 20268 min read

To connect a website screenshot MCP server to Cursor, add a server configuration in Cursor Settings → MCP or in a .cursor/mcp.json file. A documented local example is Microsoft Playwright MCP: run it with Node.js 20 or newer using npx @playwright/mcp@latest. Once connected, ask Cursor Agent to open a website and take a screenshot.

Cursor supports local command-based STDIO servers and remote URL-based MCP servers. The command, authentication, and available screenshot tools depend on the server you choose, so use the Playwright command below only for Playwright MCP. Cursor describes MCP as a way to connect Cursor to external systems and data in its MCP integrations documentation.

1. Check the prerequisites

  • Install Node.js 20 or newer for the Playwright MCP setup described here.
  • Use a Cursor version that includes MCP settings and configuration support.
  • For a different screenshot MCP provider, get its official command or remote endpoint, authentication requirements, and tool names. A server must expose a screenshot capability for Cursor to capture images.

Playwright MCP downloads its browser automatically on first use, according to its getting-started guide. The first capture may therefore take longer while the browser is installed.

2. Add Playwright MCP in Cursor settings

  1. Open Cursor Settings, then go to MCP.
  2. Choose Add new MCP Server.
  3. Name the server playwright and choose the command or STDIO server type.
  4. Set the command to npx and the argument to @playwright/mcp@latest.
  5. Save the server configuration and enable it if it is disabled.
  6. Open Cursor Agent and ask it to navigate to a target page and take a screenshot.

The Playwright MCP setup is documented in the Playwright MCP guide. The server provides a browser_take_screenshot tool with options such as full-page capture and output format; see the Playwright MCP documentation for the server’s current tool details.

3. Configure a project-level MCP server

To share the server configuration with a project, create .cursor/mcp.json at the repository root:

{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}

Save the file, then check Cursor’s MCP settings to confirm the server is connected and enabled. The configuration uses the standard command-based server shape documented by Cursor.

4. Choose project or global configuration

Configuration File Use it when
Project .cursor/mcp.json The server should be available as part of one repository’s setup.
Global ~/.cursor/mcp.json You want the server available across your Cursor projects.

Cursor merges project and global configurations; when server names overlap, project-level entries take precedence. See the Cursor MCP help documentation. Avoid committing secrets in a project configuration. If the server needs credentials, follow the provider’s instructions for environment variables or another supported credential mechanism.

5. Connect a remote MCP server

Some providers host their MCP server remotely rather than asking Cursor to launch a local process. Cursor supports URL-based server configuration and optional headers. The exact endpoint and authentication format are provider-specific; do not put the Playwright command into a remote server entry.

Use the remote configuration pattern in Cursor’s MCP documentation, substituting the provider’s documented URL and headers. Confirm whether the endpoint uses the transport Cursor supports and whether your organization permits that connection. Keep access tokens private and use the provider’s recommended secret-handling method.

6. Ask Cursor to take a screenshot

After the server is connected, ask Cursor Agent for a concrete action, for example:

Open https://example.com in the Playwright browser and take a full-page screenshot.

Cursor invokes the connected server’s tools through its MCP workflow. With Playwright MCP, the relevant tool is browser_take_screenshot. You can request a full-page image or specify an output format supported by that tool. The actual result location and available arguments can vary with the server version, so check the tool description Cursor presents if an option is unavailable.

7. Select the right connection model

Choice What it means Consider
Local STDIO Cursor launches a process on your machine, such as npx @playwright/mcp@latest. Local runtime prerequisites, package availability, and permissions to run the process.
Remote URL Cursor connects to a server endpoint supplied by a provider. Endpoint availability, authentication, headers, and network or administrator restrictions.
Project configuration Configuration lives in the repository under .cursor/mcp.json. Useful for a project-specific setup; carefully handle any credentials.
Global configuration Configuration lives in ~/.cursor/mcp.json. Useful for a personal server reused across projects.

Cursor’s built-in Browser tool and a separately configured MCP server are distinct ways to work with webpages. Use MCP when you need a connected server’s tools or integration; use the built-in browser when its managed capabilities already meet the task.

8. Permissions and access

  • Cursor may ask for approval before using MCP tools. Review the server and tool before approving, and use Cursor’s controls to allowlist trusted servers or tools if appropriate.
  • In managed environments, administrators can restrict allowed commands, URLs, or network access. If a server is blocked, check the applicable policy with your administrator.
  • Grant only the access the server needs. Browser automation can visit pages and interact with them, so consider what sites and credentials the browser session can reach.
  • If configuration uses environment variables, make sure they are available to Cursor. Cursor documents environment-variable interpolation and recommends restarting Cursor after shell-profile environment changes.

Configuration and access behavior are covered in the Cursor MCP documentation.

9. Troubleshooting

Symptom Likely cause What to do
Server does not appear or connect The configuration was not saved, the server is disabled, or the command cannot start. Check the MCP settings and the MCP Logs in Cursor’s Output panel. Confirm the command is npx, the argument is @playwright/mcp@latest, and Node.js is installed.
npx or package launch fails Node.js is missing or too old, or the environment cannot download the package. Install Node.js 20 or newer and verify the machine can reach the package registry. Restart Cursor after changing shell environment settings.
Browser starts slowly on the first request The browser download may be occurring on first use. Allow the initial setup to finish, then retry the capture. Check MCP Logs if it does not complete.
Cursor says no screenshot tool is available The connected server may not expose screenshot capture, or its connection failed. Confirm the intended server is enabled and inspect the tools it exposes. For Playwright MCP, check that browser_take_screenshot is available.
Authentication or environment variable is missing Cursor did not inherit the variable, or its configured name does not match. Check the configuration and Cursor’s MCP logs. Restart Cursor after shell-profile changes and follow the provider’s credential instructions.
Remote server connection is rejected The URL, headers, authentication, or network policy may be wrong. Compare the entry with the provider’s official instructions and check whether a managed-environment restriction applies.
Screenshot is not full page or uses an unexpected format The request did not specify the option, or the server version exposes different arguments. Ask for full-page capture or a specific supported format, then inspect the tool’s current argument description in Cursor.
Changes to a project entry appear ignored A global entry with the same name may be involved, or the JSON is invalid. Validate the JSON, check the server name and precedence, and review the merged MCP settings.

Cursor’s help documentation identifies the Output panel’s MCP Logs and server enablement controls as places to investigate connection issues. See Cursor MCP help.

10. Performance, reliability, and cost

With local Playwright MCP, capture time depends on starting the server and browser, loading the target website, and rendering the requested page. The first use may include a browser download. Full-page screenshots of long pages can take more time and produce larger image files than viewport screenshots. For repeatable capture, use a stable target page and specify the required capture mode and format in the request.

MCP connection success does not guarantee a successful page capture: a site may load slowly, block automation, or return different content based on network or browser state. Inspect the tool result and logs when a capture fails. Costs depend on your local runtime and any remote provider you choose; the Playwright setup described here does not specify a hosted screenshot API price.

Or skip the browser setup

If you need an image from one URL without setting up browser automation, ScreenshotNeo is a website screenshot API and MCP server for developers. A GET request returns a PNG, JPEG, WebP, or PDF. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for Cursor and other MCP clients.

Here is a runnable cURL request; replace the placeholder with your API key:

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

For the API documentation, request options, and other examples, see the ScreenshotNeo docs. Its clean-shot flow accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status.

ScreenshotNeo also supports full-page captures with lazy images loaded, CSS selector captures, device presets and custom viewports, PDF options, HTML or CSS input, custom CSS and JavaScript, click and wait actions, request blocking, headers and cookies, user agents, authorization, timezone and geolocation, transparent backgrounds, resizing, configurable cache TTL, signed links, asynchronous jobs with signed webhooks, bulk capture, a usage API, and an OpenAPI spec. Its parameter names are compatible with those used by other screenshot APIs to make migration easier.

There is a free plan with 1,000 screenshots per month and no card required. Paid plans start at $5 for 3,000 screenshots; every feature is available on every plan, and yearly billing gives two months free. Sign up for free and get 1,000 screenshots a month with no card.

FAQ

Can I use a screenshot MCP server in only one Cursor project?

Yes. Put its configuration in that project’s .cursor/mcp.json. Use ~/.cursor/mcp.json for a personal setup shared across projects.

Does every MCP server use the Playwright command?

No. Playwright MCP is one documented example. Follow the chosen provider’s instructions for its command or URL, credentials, prerequisites, and tool names.

Can Cursor connect to a hosted MCP server?

Yes. Cursor supports URL-based MCP server configuration, with optional headers. The provider determines the endpoint and authentication details.

Why does Cursor ask before using a screenshot tool?

Cursor has approval controls for MCP tool use. Review the server’s access and use Cursor’s settings to manage approval or allowlisting.

Keep reading