Screen MCP

屏幕mcp

在客户端机器上运行并向主机MCP公开屏幕截图工具的FastMCP服务器。它支持直接截图和基于会话的分块传输，因此LLM可以可靠地使用图像。

FastMCP官方文件： gofastmcp.com/开始/欢迎

外露工具

• list_monitors：返回检测到的监视器（索引和维度）
• capture_screenshot：以混合模式捕获屏幕图像(base64 对于非视觉，原生MCP image 视觉）
• capture_timeline：捕获定时屏幕序列（带时间戳的有序帧）
• start_timeline_capture：启动时间轴会话并返回 timeline_id
• get_timeline_manifest：返回分块的时间线元数据
• get_timeline_chunk：检索时间线JSON块
• release_timeline_capture：明确发布时间线会话
• start_screenshot_capture：启动屏幕截图会话并返回 capture_id
• get_screenshot_manifest：返回非视觉LLM的元数据和ASCII预览
• get_screenshot_chunk：返回一块base64图像数据
• release_screenshot_capture：释放截图会话并释放内存

快速工具指导

• 需要可用的监视器信息： list_monitors
• 需要一个负载适中的快速单屏幕截图： capture_screenshot
• 需要一个更强大的带有分块的单屏幕截图：

start_screenshot_capture -> get_screenshot_manifest -> get_screenshot_chunk （0..N-1）-> release_screenshot_capture

• 一次通话需要一个简短的时间表： capture_timeline
• 需要为大型有效载荷制定一个强有力的时间表：

start_timeline_capture -> get_timeline_manifest -> get_timeline_chunk （0..N-1）-> release_timeline_capture

最佳实践：

• 始终以升序连接块 chunk_index 订单。
• 总是打电话 release_* 在读取会话数据以释放内存之后。
• 对于非视觉模型，消费 preview_text 在装载全部有效载荷之前，从舱单中提取。

先决条件

• 带有活动图形会话的Linux（X11/Wayland捕获支持）
• DISPLAY 服务器进程可用的环境变量(mss 在Linux上需要它）
• Python 3.10+

本地安装

uv sync

或者通过任务文件：

task setup

运行MCP服务器（stdio）

task server

此任务使用以下命令启动服务器 mcpm run screen-mcp 通过 uvx. 它还可以在需要时自动注册或更新本地MCP服务器。 在注册过程中传播与显示相关的环境变量： DISPLAY, WAYLAND_DISPLAY, XAUTHORITY, XDG_RUNTIME_DIR.

MCP兼容烟雾测试客户端

task client

烟雾测试脚本位于 scripts/smoke_client.py 和练习：

• list_monitors
• start_screenshot_capture
• get_screenshot_manifest
• get_screenshot_chunk
• release_screenshot_capture

它将验证图像写入 artifacts/smoke_capture.jpg.

您还可以通过以下方式运行特定操作 --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.json

调试和实时检查

task inspector

这将启动针对以下对象的MCP检查器 mcpm run screen-mcp 服务器。

在VS Code中使用服务器

1. 在VS Code中打开此项目文件夹。
2. 添加一个 servers 配置。
3. 创建一个 .vscode/mcp.json 文件并添加以下示例之一。

克隆仓库（未发布的包）的推荐本地示例：

{
  "servers": {
    "screen-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "/absolute/path/to/screen-mcp", "screen-mcp"]
    }
  }
}

直接从Git仓库运行而不进行全局安装的示例：

{
  "servers": {
    "screen-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com//screen-mcp.git", "screen-mcp"]
    }
  }
}

通过MCPM的替代方案：

{
  "servers": {
    "screen-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcpm", "run", "screen-mcp"]
    }
  }
}

示例工具调用

• 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)

时间线行为 capture_timeline:

• 固定节奏： TIMELINE_FPS （默认2张图片/秒，可在源代码中配置）
• 最大持续时间： TIMELINE_MAX_DURATION_SECONDS （默认30秒，可在源代码中配置）
• 每个帧包括： frame_index, t_offset_ms, captured_at, preview_text, image_sha256, image_size_bytes
• temporal_hint 明确LLM的时间顺序

稳健的流量建议：

1. start_screenshot_capture(...) ->获得 capture_id
2. get_screenshot_manifest(capture_id) ->元数据+ preview_text
3. get_screenshot_chunk(capture_id, chunk_index) ->重新组装块
4. release_screenshot_capture(capture_id)

Base64注释

• 对于多客户端MCP，base64是最具互操作性的格式：简单、JSON友好、与视觉和非视觉客户端兼容。
• 权衡：更大的有效载荷（约33%）和单块截断的风险。
• 此项目使用基于会话的分块base64传输(capture_id)使大型交易所变得可靠。
• 对于非视力LLM，首选 get_screenshot_manifest （元数据+ASCII预览），然后下载完整图像。

混合动力模式 capture_screenshot:

• response_mode="base64" （默认）：遗留行为，JSON输出 image_base64.
• response_mode="image"：视觉模型的原生MCP图像输出，其中包含元数据 structured_content.
• response_mode="auto"：阅读 SCREEN_MCP_CAPTURE_RESPONSE_MODE (base64 或 image)并基于客户端/主机自动选择。

安全和隐私

屏幕截图可能包含敏感数据。为生产使用添加明确的客户端策略（同意、屏蔽、窗口白名单等）。