How to Use Cursor MCP for Screenshots

Short answer: For a web-page screenshot, ask Cursor Agent to use its integrated Browser tool, navigate to the URL, and capture the page. If you need your own capture system, configure an MCP server with a tool that returns the screenshot as base64 image content and a MIME type; Cursor attaches that image to chat when the selected model supports images.

This guide covers Browser screenshots, custom MCP servers, the Cursor CLI, self-hosted desktop capture, security controls, troubleshooting, and a hosted alternative. Cursor’s MCP documentation explains that servers can return screenshots and other images as base64-encoded image content, while its Browser documentation describes screenshot capture as visual feedback for Agent.

1. Choose the screenshot route

Route	Best for	What you configure
Cursor Browser	Capturing a public web page during an Agent task	Browser access and a clear prompt
Custom MCP image tool	Using your own renderer, authentication, or capture policy	An MCP server and a tool that returns typed image content
Cursor CLI	Running screenshot tasks from a terminal or automation script	The same MCP configuration used by the editor
Computer-use worker	Capturing a self-hosted desktop, local app, or authenticated browser session	Platform packages, display access, and OS permissions

2. Capture a website with Cursor Browser

1. Open Cursor and start an Agent task.
2. Ask Agent to navigate to the target URL and take a screenshot.
3. Specify what you need: the full page, the current viewport, a particular state, or a particular element.
4. Ask Agent to inspect the returned image or save it according to the Browser tool’s available actions.

Navigate to https://example.com and take a screenshot of the page. Return the screenshot so I can inspect the layout.

For a reproducible capture, include the exact URL, required state, and acceptance criteria:

Open https://example.com/pricing. Wait until the pricing cards are visible, take a screenshot of the full page, and check that the mobile navigation is closed.

The Browser route is the simplest option when Cursor itself can reach the page. The screenshot is visual context for Agent, so ask the model to verify the result when layout or browser state matters.

Useful prompt details

• URL and route: give the complete URL, including query parameters.
• State: describe sign-in status, open menus, selected tabs, cookie dialogs, or other required state.
• Timing: tell Agent to wait for a selector or visible content when the page loads asynchronously.
• Scope: say whether you need the viewport, full page, or a specific element.
• Review: ask Agent to report if navigation, loading, or capture failed.

3. Return a screenshot from a custom MCP server

A custom MCP server must do two separate jobs: obtain the screenshot, then return it in MCP image content. Cursor’s documented handoff format is a base64-encoded image string together with its MIME type. The capture engine, authentication, browser setup, and output format are decisions for your server.

Required response shape

{
  "content": [
    {
      "type": "image",
      "data": "<base64 image bytes>",
      "mimeType": "image/png"
    }
  ]
}

Use image/png, image/jpeg, or another MIME type that matches the bytes. Return an error as an MCP tool error when navigation or capture fails; do not return an empty image.

Example tool contract

Tool name: take_screenshot
Input:
  url: string
  full_page: boolean (optional)
  wait_ms: integer (optional)
Output:
  one image content block with base64 data and a MIME type

Your implementation can use Playwright, Puppeteer, Selenium, or another renderer. Keep browser startup and page navigation inside the server, and keep the MCP layer responsible for validating arguments and packaging the resulting bytes.

Configure the server in Cursor

Add the server through Cursor Marketplace or configure a custom server in mcp.json. The exact command depends on how you package your server. A generic stdio entry looks like this:

{
  "mcpServers": {
    "screenshots": {
      "command": "python",
      "args": ["/absolute/path/to/screenshot_server.py"]
    }
  }
}

After saving the configuration, restart or reload Cursor if required, enable the server, and ask Agent to use the named tool:

Use the screenshots MCP server's take_screenshot tool for https://example.com and return the image.

4. Verify MCP servers and tools

In the editor, confirm that the server is enabled and that its tools are listed. In the Cursor CLI, the documented commands are:

agent mcp list
agent mcp list-tools <server>

The CLI shares MCP configuration with the editor. A documented CLI prompt for a screenshot task is:

agent -p "Navigate to google.com and take a screenshot of the search page"

If the tool appears in agent mcp list-tools but Agent does not call it, name the tool explicitly in your prompt and describe the expected image output.

5. Capture a self-hosted desktop

Use Cursor’s separate computer-use worker when the target is a local application, a private desktop, or a browser session that cannot be reached by a normal web capture service.

macOS

1. Start the worker:

agent worker --computer-use start

2. Grant Accessibility and Screen Recording permissions to Cursor Computer Use.
3. Run a real screenshot task to verify that the worker can see and control the desktop.
4. Use agent worker debug to confirm helper installation. This command does not confirm that the two macOS permissions were granted.

Linux

Computer use relies on an X11 display and the documented desktop packages. Chrome or Chromium is optional but recommended for browser work. Verify the display, packages, and browser from the worker environment, then run an actual screenshot task.

6. Enterprise browser controls

Enterprise administrators can enable browser features and configure origin allowlists. With an allowlist, automatic navigation and MCP tool execution are limited to permitted origins. Manual navigation can still display other origins, but browser tools are blocked there. Design prompts and server permissions around the origins your policy permits.

7. Security checklist

• Verify the source of every MCP server before enabling it.
• Review the permissions requested by the server and its launcher.
• Use restricted API keys and separate credentials for development and production.
• Audit server code before granting access to private pages, files, or authenticated sessions.
• Limit automated navigation to approved origins where your enterprise policy supports it.
• Do not place long-lived secrets in prompts or screenshot URLs.

8. Troubleshooting

Symptom	Likely cause	Fix
Browser does not appear as an available tool	Browser access is disabled or the feature is unavailable in the current workspace	Check Cursor settings and workspace policy, then restart Agent.
Agent navigates but returns no image	The task did not request a screenshot clearly, or the model cannot process images	Ask explicitly for a screenshot and use a model with image support.
Custom server is listed but the tool is missing	Configuration points to the wrong command or the server failed during startup	Run agent mcp list, inspect the server command and logs, then run agent mcp list-tools <server>.
Image content is rejected	Missing base64 data, incorrect MIME type, or malformed MCP content	Return one image content block with valid base64 bytes and a matching MIME type.
Screenshot is blank	Navigation failed, the page is still loading, or the target requires authentication	Check the URL and credentials, wait for a visible selector, and ask Agent to report navigation errors.
Local desktop capture cannot see the screen	Missing macOS permissions or an unavailable Linux X11 display	Grant permissions to Cursor Computer Use on macOS; verify X11 and required packages on Linux.
Automated navigation is blocked	The destination is outside an enterprise origin allowlist	Use an approved origin or ask an administrator to update the allowlist.
CLI and editor show different tools	They are reading different configuration locations or profiles	Confirm the active profile and inspect the CLI’s server list.

9. Reliability, performance, and cost considerations

Reliability

• Use deterministic URLs and explicit wait conditions for pages that render asynchronously.
• Return structured errors from custom tools so Agent can retry or explain the failure.
• For private pages, keep authentication inside the controlled browser or server rather than exposing tokens in prompts.
• Verify the final image when the screenshot is used for visual regression, documentation, or a release decision.

Performance

• Browser startup, page navigation, JavaScript execution, and image encoding all add latency.
• Capture the viewport when a full-page image is unnecessary.
• Wait for the smallest reliable condition instead of using a long fixed delay.
• For repeated jobs, keep a browser worker warm and control concurrency in the MCP server.

Cost

Cursor’s Browser and MCP documentation does not specify a universal screenshot-service price. Your costs depend on Cursor usage, the model, browser infrastructure, bandwidth, and any external rendering API. Measure the number of navigations and image bytes in your own deployment.

10. Or skip the browser setup

ScreenshotNeo provides a hosted screenshot API and MCP server. It accepts one GET request and returns a PNG, JPEG, WebP, or PDF. Before capture it accepts cookie or consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers.

API example (see the ScreenshotNeo documentation for all 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}`);

ScreenshotNeo also offers an MCP server with take_screenshot, get_page_info, and capture_pdf tools for Claude, Cursor, and other MCP clients. It supports full-page capture, element selectors, dark mode, device presets, custom viewports, retina scale, PDF settings, custom CSS and JavaScript, clicks, waits, request blocking, headers, cookies, user agents, authorization, timezone, geolocation, transparent backgrounds, resizing, caching, signed links, asynchronous jobs, bulk capture of up to 100 URLs per call, usage reporting, and an OpenAPI specification.

The Free plan includes 1,000 shots per month with no card. Paid plans start at $5 for 3,000 shots; every feature is available on every plan. Create a free ScreenshotNeo account.

11. FAQ

Can Cursor MCP send a screenshot directly into chat?

Yes. A custom MCP tool can return an image content block containing base64 data and a MIME type. Cursor attaches the returned image when the selected model supports images.

Do I need an MCP server for Cursor Browser screenshots?

No. Use the integrated Browser tool for ordinary web-page captures. Add a custom server when you need your own renderer, access policy, or capture features.

Can the Cursor CLI use the same MCP tools as the editor?

Yes. Cursor documents that CLI MCP shares configuration with the editor. Use agent mcp list and agent mcp list-tools <server> to inspect it.

Which route should I use for a local desktop?

Use the computer-use worker and complete the macOS Accessibility and Screen Recording setup or the Linux X11 setup before running a real screenshot task.

What is the simplest hosted option for clean website screenshots?

ScreenshotNeo removes consent banners, popups, and chat widgets before capture, does not bill failed or blocked pages, and connects to Cursor through MCP.