[Bug]: Screenshot MCP Tool saving to Docker filesystem and not providing PNG.

[JewceCookie]

crawl4ai version

0.8.0

Expected Behavior

When calling the screenshot MCP tool with an output path, I expect it to save it to that path on my file system. I also expect it to save a PNG, as described in the MCP tool description: "Capture a full-page PNG screenshot of the specified URL [...]"
Example usage:
url: https://example.com
screenshot_wait_for: 2
output_path: C:\my\path\screenshot.png

Current Behavior

The screenshot is saved to the file system of my docker container (in the /app/ folder), running on a different computer.
I wasn't able to check the file saved to my docker filesystem, but when calling the tool without an output path, I am not returned PNG, but rather (base-64 encoded, which is fine) BMP.

Is this reproducible?

Yes

Inputs Causing the Bug

-Crawl4Ai Docker container running on my linux server
-I am using Windows
-I installed the MCP tool to cursor.

Steps to Reproduce

Ask the cursor AI agent to use the screenshot tool to save a png image to a specific path.

Code snippets

OS

Windows (me), Linux (MCP Server)

Python version

/

Browser

/

Browser version

/

Error logs & Screenshots (if applicable)

No response

[Ahmed-Tawfik94]

Problem Description

The user reports two related issues with the screenshot MCP tool:

1. Docker Filesystem Issue: When specifying an output_path like C:\my\path\screenshot.png, the screenshot is saved to the Docker container's filesystem instead of the user's local filesystem.

2. Format Issue: The returned screenshot is in BMP format instead of PNG format as documented.

Test 1: BMP Format Issue

Result: 🐛 BUG CONFIRMED

Test Method:

curl -X POST http://localhost:11235/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://en.wikipedia.org/wiki/Main_Page", "screenshot_wait_for": 2}'

Actual Results:

✓ Screenshot received (15310152 bytes base64)
[RESULT] Actual image format: BMP
         Image size: (1080, 3544)
         Image mode: RGB

🐛 BUG CONFIRMED: Format is BMP, not PNG as documented!
   Documentation states: 'Capture a full-page PNG screenshot'
   Actual format: BMP

Control Test (Short Page):

[RESULT] Short page format: PNG
         Size: (1080, 600)

Root Cause Analysis

Code Location: crawl4ai/async_crawler_strategy.py, line 1890

Problematic Code:

# Line 1890 in take_screenshot_scroller() method:
stitched.save(buffered, format="BMP", quality=85)

Explanation:

• For short pages (no scrolling): Uses take_screenshot_naive() → Playwright default → PNG ✅
• For long pages (requires scrolling): Uses take_screenshot_scroller() → BMP ❌
• The MCP tool docstring says "PNG screenshot" but code explicitly saves BMP

Impact:

• Wikipedia pages, long articles, and any scrollable content returns BMP
• Short pages (example.com) correctly return PNG
• Inconsistent behavior based on page length

---

Test 2: Docker Filesystem Path Issue

Result: 🐛 BUG CONFIRMED

Test Method:

curl -X POST http://localhost:11235/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "output_path": "/tmp/test_screenshot.png"}'

Actual Results:

[RESPONSE] {
  "success": true,
  "path": "/tmp/test_screenshot.png"
}

[ANALYSIS] Server reports file saved to: /tmp/test_screenshot.png
❌ File does NOT exist on host at expected location
   Expected: /tmp/crawl4ai_test_1758/test_screenshot.png

[CHECK] Verifying file exists in container...
✓ File exists in container:
   -rw-r--r-- 1 appuser appuser 16668 Feb 20 07:40 /tmp/test_screenshot.png

🐛 BUG CONFIRMED: File saved to container filesystem only!
   User cannot access this file from host machine.

Root Cause Analysis

Code Location: deploy/docker/server.py, lines 398-403

Problematic Code:

if body.output_path:
    abs_path = os.path.abspath(body.output_path)  # Resolves to container filesystem
    os.makedirs(os.path.dirname(abs_path), exist_ok=True)
    with open(abs_path, "wb") as f:
        f.write(base64.b64decode(screenshot_data))
    return {"success": True, "path": abs_path}  # Path is meaningless outside container

Explanation:

1. User provides path: /tmp/test_screenshot.png
2. Server runs inside Docker container with isolated filesystem
3. os.path.abspath() resolves to /tmp/test_screenshot.png inside container
4. File is saved successfully inside container only
5. Returned path /tmp/test_screenshot.png refers to container, not host
6. User on host machine cannot access this file