Screen MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Screen MCP take a screenshot of my main monitor"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
screen-mcp
A FastMCP server that runs on the client machine and exposes screenshot tools to a host MCP. It supports both direct screenshot capture and session-based chunked transfers so an LLM can consume images reliably.
Official FastMCP documentation: gofastmcp.com/getting-started/welcome
Exposed tools
list_monitors: returns detected monitors (index and dimensions)capture_screenshot: captures a screen image with hybrid mode (base64for non-vision, native MCPimagefor vision)capture_timeline: captures a timed screen sequence (ordered frames with timestamps)start_timeline_capture: starts a timeline session and returns atimeline_idget_timeline_manifest: returns chunked timeline metadataget_timeline_chunk: retrieves a timeline JSON chunkrelease_timeline_capture: explicitly releases a timeline sessionstart_screenshot_capture: starts a screenshot session and returns acapture_idget_screenshot_manifest: returns metadata plus ASCII preview for non-vision LLMsget_screenshot_chunk: returns a chunk of base64 image datarelease_screenshot_capture: releases the screenshot session and frees memory
Related MCP server: MCP Screenshot Server
Quick tool guidance
Need available monitor info:
list_monitorsNeed a fast single screenshot with moderate payload:
capture_screenshotNeed a more robust single screenshot with chunking:
start_screenshot_capture->get_screenshot_manifest->get_screenshot_chunk(0..N-1) ->release_screenshot_captureNeed a short timeline in one call:
capture_timelineNeed a robust timeline for large payloads:
start_timeline_capture->get_timeline_manifest->get_timeline_chunk(0..N-1) ->release_timeline_capture
Best practices:
Always concatenate chunks in ascending
chunk_indexorder.Always call
release_*after reading session data to free memory.For non-vision models, consume
preview_textfrom the manifest before loading full payload.
Prerequisites
Linux with an active graphical session (X11/Wayland capture support)
DISPLAYenvironment variable available to the server process (mssrequires it on Linux)Python 3.10+
Local installation
uv syncOr via Taskfile:
task setupRun the MCP server (stdio)
task serverThis task starts the server using mcpm run screen-mcp through uvx.
It also registers or updates the local MCP server automatically when needed.
Display-related environment variables are propagated during registration: DISPLAY, WAYLAND_DISPLAY, XAUTHORITY, XDG_RUNTIME_DIR.
MCP-compatible smoke-test client
task clientThe smoke-test script is located in scripts/smoke_client.py and exercises:
list_monitorsstart_screenshot_captureget_screenshot_manifestget_screenshot_chunkrelease_screenshot_capture
It writes a verification image to artifacts/smoke_capture.jpg.
You can also run a specific action via --action:
uv run python scripts/smoke_client.py --action list-monitors
uv run python scripts/smoke_client.py --action capture-screenshot --monitor-index 0 --output artifacts/capture.jpg
uv run python scripts/smoke_client.py --action capture-timeline --duration-seconds 6 --output artifacts/timeline.json
uv run python scripts/smoke_client.py --action capture-timeline-session --duration-seconds 6 --chunk-size 120000 --output artifacts/timeline_session.jsonDebugging and real-time inspection
task inspectorThis launches the MCP Inspector against the mcpm run screen-mcp server.
Using the server in VS Code
Open this project folder in VS Code.
Add a
serversconfiguration.Create a
.vscode/mcp.jsonfile and add one of the examples below.
Recommended local example for a cloned repo (unpublished package):
{
"servers": {
"screen-mcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "--project", "/absolute/path/to/screen-mcp", "screen-mcp"]
}
}
}Example for running directly from a Git repo without global installation:
{
"servers": {
"screen-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/<owner>/screen-mcp.git", "screen-mcp"]
}
}
}Alternative via MCPM:
{
"servers": {
"screen-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["mcpm", "run", "screen-mcp"]
}
}
}Example tool calls
list_monitors()capture_screenshot(monitor_index=0, image_format="jpeg", max_width=1600, quality=80)capture_screenshot(monitor_index=0, image_format="jpeg", max_width=1600, quality=80, response_mode="image")capture_timeline(duration_seconds=10, monitor_index=0, image_format="jpeg", max_width=900, quality=70)start_timeline_capture(duration_seconds=10, monitor_index=0, image_format="jpeg", max_width=900, quality=70, chunk_size=120000)get_timeline_manifest(timeline_id)get_timeline_chunk(timeline_id, chunk_index)release_timeline_capture(timeline_id)
Timeline behavior in capture_timeline:
fixed cadence:
TIMELINE_FPS(default 2 images/s, configurable in source)maximum duration:
TIMELINE_MAX_DURATION_SECONDS(default 30s, configurable in source)each frame includes:
frame_index,t_offset_ms,captured_at,preview_text,image_sha256,image_size_bytestemporal_hintmakes chronological order explicit for an LLM
Robust flow recommendation:
start_screenshot_capture(...)-> obtaincapture_idget_screenshot_manifest(capture_id)-> metadata +preview_textget_screenshot_chunk(capture_id, chunk_index)-> reassemble chunksrelease_screenshot_capture(capture_id)
Base64 notes
For multi-client MCP, base64 is the most interoperable format: simple, JSON-friendly, compatible with vision and non-vision clients.
Tradeoff: larger payload (~33%) and risk of single-block truncation.
This project uses session-based chunked base64 transfer (
capture_id) to make large exchanges reliable.For non-vision LLMs, prefer
get_screenshot_manifest(metadata + ASCII preview) before downloading the full image.
Hybrid mode in capture_screenshot:
response_mode="base64"(default): legacy behavior, JSON output withimage_base64.response_mode="image": native MCP image output for vision models, with metadata instructured_content.response_mode="auto": readsSCREEN_MCP_CAPTURE_RESPONSE_MODE(base64orimage) and chooses automatically based on the client/host.
Security and privacy
Screen captures may contain sensitive data. Add an explicit client-side policy for production use (consent, masking, window whitelisting, etc.).
Available Tools
11 toolscapture_screenshotA
Capture one screenshot in a single call.
Prefer this tool for small/medium payloads when a one-shot response is desired.
For larger payloads or robust transport, use the session flow:
start_screenshot_capture -> get_screenshot_manifest -> get_screenshot_chunk -> release_screenshot_capture.
Args: monitor_index: 0 captures the virtual full desktop, 1..N capture a specific monitor. image_format: png or jpeg. max_width: optional resize target width while preserving aspect ratio. quality: JPEG quality in [1, 100]. Ignored for PNG. response_mode: 'base64' (default), 'image' (native MCP image block), or 'auto' (resolved from SCREEN_MCP_CAPTURE_RESPONSE_MODE env var).
Inputs: monitor_index, image_format, max_width, quality, +1 more.
capture_timelineA
Capture a timeline in a single call.
Prefer this tool for short timelines when a one-shot JSON payload is acceptable.
For larger timeline payloads or safer transport, use the session flow:
start_timeline_capture -> get_timeline_manifest -> get_timeline_chunk -> release_timeline_capture.
Max duration is enforced by source constant
TIMELINE_MAX_DURATION_SECONDS.Capture rate is fixed by source constant
TIMELINE_FPS(images/second).Output is optimized for temporal reasoning by an LLM.
Inputs: duration_seconds (required), monitor_index, image_format, max_width, +1 more. Returns: object
get_screenshot_chunkB
Return one base64 chunk for a screenshot session.
Fetch chunks from chunk_index=0 to total_chunks-1 and concatenate chunk_base64.
Inputs: capture_id (required), chunk_index (required). Returns: object
get_screenshot_manifestA
Return screenshot session metadata and an ASCII preview.
Use this as step 2 after start_screenshot_capture to discover total_chunks and preview content.
Inputs: capture_id (required). Returns: object
get_timeline_chunkA
Return one JSON text chunk for a timeline session.
Use this after get_timeline_manifest; fetch chunks from chunk_index=0 to total_chunks-1 in order.
Concatenate chunk_text values to reconstruct the full timeline JSON.
Inputs: timeline_id (required), chunk_index (required). Returns: object
get_timeline_manifestA
Return timeline session metadata without the full payload.
Use this as step 2 after start_timeline_capture to discover total_chunks and validate integrity metadata.
Inputs: timeline_id (required). Returns: object
list_monitorsA
List available monitors.
Use this first when the caller does not know which monitor index to target.
index=0 is the virtual full desktop, index>=1 targets a specific monitor.
Inputs: no named parameters. Returns: result
release_screenshot_captureA
Release a screenshot session and free memory.
Call this after reading all required chunks.
Inputs: capture_id (required). Returns: object
release_timeline_captureA
Release a timeline session and free memory.
Call this after reading all required chunks.
Inputs: timeline_id (required). Returns: object
start_screenshot_captureA
Capture a screenshot and store it in a temporary server-side session.
Use this as step 1 of the chunked screenshot flow.
Next calls should be: get_screenshot_manifest, then all get_screenshot_chunk, then release_screenshot_capture.
Inputs: monitor_index, image_format, max_width, quality, +1 more. Returns: object
start_timeline_captureA
Capture a timeline and store it in a temporary chunked session.
Use this as step 1 of the chunked timeline flow.
Next calls should be: get_timeline_manifest, then all get_timeline_chunk, then release_timeline_capture.
Inputs: duration_seconds (required), monitor_index, image_format, max_width, +2 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Every tool has a clearly distinct purpose with no ambiguity. The screenshot and timeline tools are cleanly separated into one-shot and session-based variants, and the session flow tools (start/get/release) are clearly differentiated by their specific roles in the capture process. The list_monitors tool serves a unique discovery function.
The tool names follow a perfectly consistent verb_noun pattern throughout. All screenshot tools use 'screenshot' and all timeline tools use 'timeline' with consistent prefixes (capture_, start_, get_, release_). The pattern is maintained across all 11 tools with no deviations.
The 11 tools are well-scoped for a screen capture server. They provide complete coverage for both screenshot and timeline capture with both one-shot and session-based approaches, plus monitor discovery and session management. Each tool earns its place without redundancy or bloat.
The tool surface provides complete coverage for screen capture operations. It supports both screenshots and timelines, offers both simple one-shot and robust chunked transport methods, includes session lifecycle management (start/get/release), and provides monitor discovery. No obvious gaps exist for the stated domain.
Maintenance
Related MCP Connectors
OCR, transcription, file extraction, and image generation for AI agents via MCP.
Web scraping, browser automation, screenshots and AI data extraction for AI agents via MCP.
Grabbit gives AI agents eyes on the web through a hosted MCP server. Send a public URL and get a pixel-perfect hosted image back, without maintaining Chromium, Playwright, or a browser fleet. Capture a full page, exact viewport, or single CSS selector as PNG, JPEG, or WebP. Grabbit handles cookie and consent banners, waits for JavaScript-heavy pages, blocks private and internal URLs, supports safe retries with idempotency keys, and delivers async results through signed webhooks. Completed captures include a CDN URL. Connect with OAuth 2.1 or an API key. Grabbit works with Claude, Cursor, Codex, and any MCP client. Live captures cost $0.002 each. The $50 annual plan includes 25,000 prepaid credits that never reset or expire. Free test keys return placeholder images, so you can wire up the integration before paying. Home: https://grabbit.live Docs: https://grabbit.live/screenshot-api Built by BrainGrid.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI tools to capture and process screenshots of a user's screen, allowing AI assistants to see and analyze what the user is looking at through a simple MCP interface.126MIT
- AlicenseNot gradedqualityNot gradedmaintenanceEnables LLMs to capture and analyze screenshots of your screen, windows, or regions with smart detection capabilities. Features natural language queries, automatic window targeting, and text enhancement for UI debugging and visual inspection.2MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI assistants to capture and analyze screen content across multi-monitor setups with smart image optimization. Provides screenshot capabilities and detailed monitor information for visual debugging, UI analysis, and desktop assistance.-
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to capture multi-monitor screenshots with coordinate grids and perform mouse, keyboard, scrolling, dragging, and window-management actions on Windows via MCP tools or CLI. It provides pixel-accurate desktop automation for computer-use agents.MIT