How to Run a Website Screenshot MCP Server with Docker

To run a website screenshot MCP server with Docker, choose a transport first: use stdio when your MCP client should launch the container, or HTTP when the container should stay running and the client can connect to a URL. For a documented browser automation project, start with Microsoft Playwright MCP. Its persistent Docker server listens on port 8931 at http://localhost:8931/mcp. A separate Python screenshot MCP project offers its own stdio and HTTP commands on port 8000; its commands and capabilities are different.

This guide covers those two MCP-first deployments, where screenshots are saved, what Docker can and cannot capture, and how to diagnose common setup problems. These are documented project configurations, not claims that either setup has been tested here. Check the current upstream instructions before running them because images and commands can change.

1. Choose stdio or HTTP

Transport	How it works	Use it when
stdio	The MCP client starts Docker and exchanges messages with the container over standard input and output.	You want the client to manage the server lifecycle and do not need a separate service URL.
HTTP	You start a long-lived container, publish its port, and configure the client with the server’s MCP URL.	The server should stay available independently of one client process and your MCP client supports a URL endpoint.

Transport support depends on the client. The screenshot-server project also documents SSE, but do not assume a particular client supports every transport. For HTTP, the examples below bind a port on the Docker host. The project documentation does not establish a universal authentication, TLS, or internet-exposure configuration. As a prudent deployment inference, keep an unconfigured local service within a trusted environment and consult the selected project’s current security guidance before making it reachable outside your machine.

2. Run Microsoft Playwright MCP in a persistent Docker container

Microsoft Playwright MCP documents a persistent HTTP setup. Run this command to start a container in the background and map host port 8931 to container port 8931:

docker run -d -i --rm --init --pull=always \
  --entrypoint node \
  --name playwright \
  -p 8931:8931 \
  mcr.microsoft.com/playwright/mcp \
  /app/cli.js --headless --browser chromium --no-sandbox --port 8931 --host 0.0.0.0

Configure an MCP client that supports URL-based servers with the documented endpoint:

{
  "mcpServers": {
    "playwright": {
      "url": "http://localhost:8931/mcp"
    }
  }
}

Here, localhost means the machine where the client can reach the published Docker port. If the client runs in another container or on another machine, its localhost may refer to a different network namespace; use an address reachable from that client and configure networking accordingly.

What this container can capture

The Playwright MCP repository says its Docker implementation currently supports headless Chromium only. Its browser_take_screenshot tool captures browser content. An optional filename can save the screenshot; without an explicit name, the tool uses its output directory and a timestamped filename. The documented filename resolution can depend on whether a filename was supplied: paths may resolve against the workspace root or output directory. Check the project’s current documentation for the exact tool arguments and output-directory behavior.

This is a browser screenshot workflow. It does not capture the physical desktop that is hosting Docker.

Alternative: let the MCP client launch the container over stdio

If you prefer client-managed startup, the repository documents this MCP configuration:

{
  "mcpServers": {
    "playwright": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "--init", "--pull=always", "mcr.microsoft.com/playwright/mcp"]
    }
  }
}

In this arrangement, the MCP client runs Docker as a subprocess. You do not publish port 8931 because the connection uses stdio. Configure this only in an MCP client that supports launching local commands.

3. Alternative: build and run mcp-screenshot-server

aamar-shahzad/mcp-screenshot-server is a separate screenshot MCP project with its own Docker image, transports, and features. Its README documents building the image from a local checkout. In the directory containing its Dockerfile, run:

docker build -t mcp-screenshot-server .

For stdio, let the MCP client launch the container:

docker run -i --rm mcp-screenshot-server

For its streamable HTTP example, publish port 8000:

docker run -p 8000:8000 mcp-screenshot-server \
  --transport streamable-http --port 8000

The README gives http://localhost:8000/mcp as the MCP endpoint for a Cursor configuration. It lists MCP_HOST with a default of 0.0.0.0 and MCP_PORT with a default of 8000. For example, a URL-based client configuration following that endpoint is:

{
  "mcpServers": {
    "screenshot": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Use that JSON only if your client supports URL-based MCP configuration. The project also documents SSE; check both the client’s transport support and the project’s current instructions before choosing it.

Save screenshot files to the host

A file written inside a container is not automatically a host file. The screenshot-server README documents mounting a host directory at /app/screenshots:

mkdir -p screenshots
docker run -p 8000:8000 \
  -v "$(pwd)/screenshots:/app/screenshots" \
  mcp-screenshot-server --transport streamable-http

Files the project writes under /app/screenshots will be available under the host’s screenshots directory. Confirm the tool’s output path and filename behavior in the project documentation; a volume mount only helps when the application writes into the mounted container path. The exact mount syntax shown is for a POSIX-style shell.

4. Know whether you need a webpage or desktop screenshot

A headless browser screenshot captures a webpage rendered by the browser. A desktop screenshot captures the actual screen of the host operating system. These are different tasks. The screenshot-server project warns that its headless Docker environment can produce blank results for actual screen capture and says real desktop capture requires running natively on the host. For a webpage, use the browser screenshot tool; for the host’s physical desktop, use an approach designed to run on that desktop rather than assuming a headless container can see it.

A third profile is mcp-server-screenshot, described on PyPI as a Docker Compose local screenshot API and MCP server at http://localhost:8500. Its page describes PNG, JPEG, and PDF output, viewport settings, full-page capture, waiting for a CSS selector, and an optional delay. It is a local API-plus-MCP alternative, but the inspected project page does not provide the same complete Docker-to-MCP-client command flow as the two examples above. Treat it as a separate deployment profile and follow its own current documentation.

5. Troubleshoot common problems

Symptom	Likely cause	What to check
The MCP client cannot connect to the server	The container is stopped, the wrong port is published, the URL path is wrong, or the client cannot reach the Docker host.	For Playwright, check port 8931 and `/mcp`; for mcp-screenshot-server, check port 8000 and `/mcp`. Confirm the container is running and that the address is reachable from the client’s network namespace.
The stdio server does not start in the client	The client may not support command-launched MCP servers, Docker may be unavailable to the client process, or the configured command or arguments may differ from the project’s current instructions.	Run the corresponding Docker command in a terminal, confirm Docker is available to the client, and verify its local-command MCP configuration format.
The screenshot is blank when capturing a desktop	A headless container does not have the host’s visible desktop session.	Confirm the target is a webpage or a physical desktop. The screenshot-server project’s guidance is to run natively on the host for actual screen capture.
The screenshot is missing from the host	The tool may save elsewhere, or the container path may not match the mounted volume.	Check the tool’s filename and output-directory rules, mount the directory the application writes to, and confirm the host path exists.
Port 8000 or 8931 is already in use	Another host process is listening on the selected port.	Stop that process or publish a different host port, then set the client URL to the new host port. Keep the container-side port consistent with the server’s configured port.
The command runs but the client rejects the transport	The client may not support that project’s selected transport.	Check client support. Use stdio when the client launches a command, or HTTP when it supports a URL endpoint; do not assume SSE or streamable HTTP support.

6. Deployment checklist, reliability, and cost

Choose stdio for a client-launched process or HTTP for a persistent server your client can reach.
Match the client configuration to the selected project’s endpoint and transport.
Publish the correct host port: 8931 for the documented Playwright MCP container, or 8000 for the screenshot-server HTTP example.
Mount a host volume when output files must survive container removal, and verify the application’s actual output directory.
Check whether the task is a webpage capture or a physical desktop capture.
Before relying on an image tag in a repeatable deployment, decide how you will control image updates. The Playwright example uses --pull=always; the other example builds a local image. The cited instructions do not provide a validated version pin.
For failures, inspect the container’s current state and logs, then check the project’s latest README for changed flags or tool behavior.

Both documented patterns use a browser in a container, so capture time and resource use depend on the page, browser startup, and container environment. The dossier does not provide comparative performance benchmarks, reliability figures, or pricing for these self-hosted projects; measure them in your own workload and account for the host resources and maintenance your deployment requires. The examples do not establish production security protections such as authentication or TLS.

7. Or skip the browser setup

If you need screenshot output without managing a browser container and MCP transport, ScreenshotNeo is a website screenshot API and MCP server for developers, made by Yorker Media. Its MCP server works with Claude, Cursor, and any MCP client. A one-call API request returns a screenshot or PDF; see the ScreenshotNeo API documentation.

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}`);

Cookie banners are accepted and removed before the shot, along with known consent platforms, newsletter popups, and chat widgets. Each step can be turned off.
Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers say the page verdict and billing status.
The MCP server provides take_screenshot, get_page_info, and capture_pdf for AI agents.
The free plan includes 1,000 screenshots a month with no card. Paid plans start at $5 for 3,000 screenshots.

Frequently asked questions

Can I use a remote machine instead of localhost?

Yes, if the container’s published port is reachable from the MCP client and that client supports the selected transport. The examples here do not define authentication or a production exposure setup, so consult the project’s security guidance before making a service reachable outside a trusted environment.

Do the two MCP Docker examples use the same tools?

No. They are separate projects with different documented commands and capabilities. Choose based on the project’s current tool documentation and the transport your client supports.

Does a Docker screenshot server capture PDFs?

The cited Playwright MCP and mcp-screenshot-server material here is about screenshot workflows. The separate PyPI project describes PNG, JPEG, and PDF support; check that project’s own API and deployment instructions for details.

How do I keep output files after the container exits?

Write them to a mounted host directory where the project supports file output. The screenshot-server example mounts the host’s screenshots directory at /app/screenshots.