This server lets coding agents capture and view real screenshots to visually inspect what they built.
take_screenshot captures the screen and returns the image directly to the agent; monitor=0 stitches all monitors together, while 1..N selects a specific display.
list_monitors lists available monitor numbers and resolutions so you can choose the right monitor for take_screenshot.
Works cross-platform on Windows, macOS, and Linux, with platform-specific setup notes.
Screenshots are downsampled and compressed to fit MCP output token limits.
The same package can also be used as a Claude Code hook helper to automatically capture screenshots after agent actions.
Click on "Install 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., "@screenshot-feedback-hook-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.
中文 | English
让 coding agent 看到自己产出的真实画面 —— 跨平台截图反馈工具（MCP server + Claude Code hook 双层）。
Let your coding agent see what it builds: a cross-platform (Windows / Linux / macOS) screenshot-feedback tool for AI agents, shipped as an MCP server plus a Claude Code hook helper.
Agent 写前端、画 EasyEDA/CAD 工程图时，没有视觉反馈就只能猜。给它一个「截图 → 看图 → 自我纠正」的回路，产出质量立刻不一样。
技术现实：Claude Code 的 hook 只能回传文本，而 MCP 工具可以回传原生图片。所以本工具做成双层：
层 | 触发方式 | 图片如何进入 agent 视野 |
MCP server | agent 主动调用 | 工具直接返回原生图片块（跨 MCP 客户端通用） |
Claude Code hook | 某操作后自动触发 | hook 回传截图的绝对路径，agent 用 Read 工具读图 |
DeepSeek Harness 插件 | agent 主动调用，或操作后 / 轮次结束时自动触发 | 截图存进 dsh 的持久附件库，作为图片块直接进上下文，agent 什么都不用做 |
图片默认降采样（最长边 1568px）并按字节预算（~80KB）迭代压缩 JPEG，避开 Claude Code 对 MCP 输出 ~25k token 的限制。
推荐工程师 / 非程序员用户：直接让 AI agent 替你安装配置，没必要手动编辑 JSON。 在 Claude Code 里说一句「帮我安装并配置 screenshot-feedback-hook-mcp」，agent 会按下文 hook 配置 的提示先问清你的使用场景（看什么画面、渲染多久、何时截图），再替你写好 MCP + hook 配置。想自己动手的见下面的手动步骤。
Related MCP server: snapdiff-mcp
零安装运行（需要 uv）：
# MCP server（无参数 = MCP server）
uvx screenshot-feedback-hook-mcp
# CLI 截图（带子命令 = CLI）
uvx screenshot-feedback-hook-mcp capture --monitor 0 --out shot.jpg
uvx screenshot-feedback-hook-mcp monitors或常驻安装：pipx install screenshot-feedback-hook-mcp / uv tool install screenshot-feedback-hook-mcp。
Claude Code 一行：
claude mcp add screenshot-feedback -- uvx screenshot-feedback-hook-mcp或任意 MCP 客户端（Cursor / Cline / Windsurf...）的 mcp.json：
{
"mcpServers": {
"screenshot-feedback": {
"command": "uvx",
"args": ["screenshot-feedback-hook-mcp"]
}
}
}工具：
take_screenshot(monitor=0) —— 截屏，直接返回图片。0=全部显示器拼接，1..N=单屏。
list_monitors() —— 列出显示器编号/分辨率。
DeepSeek Harness 用户请走原生插件，别走上面的 MCP：dsh 有持久图片附件服务，插件可以把截图直接变成图片块推进上下文，agent 不需要主动调任何工具。
dsh plugin --profile web add dsh-screenshot-feedback-hook-mcp
dsh web本包是一个 dsh 组合包（bundle）：package.json 里的 dsh.bundle.patch 指向包内自带的 cordis.patch.yml。dsh plugin add 认出这个 manifest 后，会把包名追加进 profile 的 dsh.profile.bundles，那一层 patch 随即组合进配置树 —— 你不需要手写任何 patch。装完用 dsh --profile web --dump-config 能看到多出来的 # == dsh-screenshot-feedback-hook-mcp 层和 id: screenshot-feedback 那一行。
要求 dsh ≥ v0.1.0-rc.8、PATH 上有 pnpm、Python 包 ≥ 0.3.0、插件 ≥ 0.2.0，以及一个支持图片输入的模型。
插件 0.1.0 有严重缺陷，装了会让该 profile 里的所有工具调用崩掉（不只是截图）。请升级到 ≥ 0.2.0，升级步骤见 dsh-plugin/README.zh.md。
DeepSeek 的 deepseek-v4-flash 和 deepseek-v4-pro 都是纯文本模型，rc.8 的内置 deepseek-official 路由也没有自带任何视觉模型。用它们的话截图根本进不了上下文（dsh 会在发请求前拒掉），所以插件会跳过截图并告诉你怎么换：在「设置 → 模型」加一个 Anthropic / OpenAI 等 catalog provider 选视觉模型，或给自定义 provider 的模型声明 input: [text, image]。注意设置页填不了模态 —— 加完模型要点「打开配置文件」，在 settings.yaml 里手工补这个字段（llm-deepseek 下叫 inputModalities）。
装好后可以在 设置 → 插件 → 插件配置 → 截图反馈 那张卡片上直接调参（显示器、各种等待时间、两个默认关闭的自动截图时机等），存完免重启即生效。完整字段表与工作原理见 dsh-plugin/README.zh.md。
如果你是替用户配置本工具的 AI agent：在写入任何 hook 配置之前，请先询问用户的使用场景。 hook 的正确配置高度依赖场景，盲配多半会截到无关画面或时机不对。至少要问清：
要看什么画面？ 前端页面（浏览器）、工程图（EasyEDA/CAD 等桌面应用）、还是别的？决定 --monitor（视觉输出在哪个屏幕）。
画面渲染/刷新需要多久？ 浏览器热重载约 1–2s，EDA/CAD 重绘可能更久 → 决定 --delay。
什么时候截？ 每次 Claude 停下来时（Stop，最省心）还是每次改完文件后（PostToolUse + matcher，更密集）？
配在哪一层？ 仅当前项目（项目 .claude/settings.json）还是所有项目（用户级 ~/.claude/settings.json）？
问清后再从下面的模板里挑一个、填好参数写入。不要默认照抄。
第 1 步 · 选触发时机
触发 | 何时截图 | 适合 |
| Claude 每次回答结束时截一张 | 大多数场景，频率适中、省心 |
| 每次匹配到的工具（如 | 想在每次改动后立刻看到效果 |
第 2 步 · 按场景填参数
--monitor N：视觉输出所在的显示器。0=全部拼接，1..N=单屏。先跑 uvx screenshot-feedback-hook-mcp monitors 看编号。
--delay 秒：截图前等待，确保画面渲染完成（前端 1、EDA/CAD 视渲染速度可设 2~5）。
--max-edge 像素 / --target-kb 体积：一般用默认即可（最长边 1568px、~80KB）。
第 3 步 · 写入 .claude/settings.json
项目级配置放项目根目录的 .claude/settings.json；想全局生效放用户级 ~/.claude/settings.json。模板见下方与 examples/。
第 4 步 · 验证
重启 Claude Code 会话，触发一次对应事件，确认 Claude 收到「截图已保存到 …」并主动用 Read 读了图。
Stop，推荐起点）{
"hooks": {
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "uvx screenshot-feedback-hook-mcp capture --delay 1 --hook-output stop"
}
]
}
]
}
}PostToolUse）{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "uvx screenshot-feedback-hook-mcp capture --delay 2 --hook-output post-tool-use"
}
]
}
]
}
}CLI 会输出正确的 hook JSON（Stop 用 decision:block 回传文字并自动处理 stop_hook_active 防死循环；PostToolUse 用 hookSpecificOutput.additionalContext），agent 看到「截图已保存到 …，请用 Read 工具读取」后会读图。因为 hook 只能回传文本，所以走「回传路径 + agent 用 Read 读图」这条路；想让 agent 直接拿到图片块请用上面的 MCP 方式。
Windows：开箱即用。
macOS：首次使用需在「系统设置 → 隐私与安全性 → 屏幕录制」勾选运行 agent 的终端/IDE 并重启该应用。未授权时截到的不是黑屏，而是壁纸 + 菜单栏 —— 其他应用的窗口一个都不在图里。
⚠️ 未授权不一定会被检测出来，请先手动验证一次。 现在的检测是事后启发式（
core/platform_check.py的capture_warning）：把画面缩到 16×16 看灰度极差，只有接近纯色（纯黑、纯色壁纸）才会给出提示。照片壁纸下不会触发，而那正是 macOS 的默认样子。也就是说你可能拿到一张「看起来完全正常的桌面截图」、一句警告都没有，而你要看的窗口根本不在图里 —— 比黑屏更难察觉，agent 会以为是自己的页面没渲染出来，跑去 debug 一份没问题的代码。在授权确定之前，先手动跑一次
uvx screenshot-feedback-hook-mcp capture --out shot.jpg并亲眼看一下图里有没有你的窗口，再交给 agent。确定性的检测（
CGPreflightScreenCaptureAccess()，与画面内容无关）在 roadmap 上，缺一台 macOS 机器验证。
Linux：X11 开箱即用；纯 Wayland 下 mss 受限，工具启动时会探测并提示（grim/portal 后端在 roadmap）。
区域截图（--region x,y,w,h）
按窗口标题截图（Win EnumWindows / mac CGWindowList / Linux wmctrl）
URL / 无头浏览器模式（前端确定性截图）
Wayland 后端（grim / xdg-desktop-portal）
macOS 屏幕录制授权的确定性检测（CGPreflightScreenCaptureAccess），替掉现在会漏检照片壁纸的纯色启发式
uv sync # 安装依赖
uv run pytest # 测试
uv run screenshot-feedback-hook-mcp capture --out shot.jpg # CLI
uv run screenshot-feedback-hook-mcp # MCP serverMIT License.
列出可用显示器编号与分辨率，供 take_screenshot 选择 monitor 参数。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It describes the output as a list of monitor numbers and resolutions but does not explicitly state it is a read-only, safe operation. However, for a simple list tool with no parameters, the lack of further behavioral disclosure is minimally acceptable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single well-structured sentence that front-loads the action and purpose, with no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is very simple with no parameters and an output schema present. The description completely covers its purpose and relationship to the sibling tool, requiring no further explanation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, and schema coverage is 100%. The description correctly handles this by not adding unnecessary param info, fitting the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists available monitor numbers and resolutions, and explicitly connects it to the sibling tool take_screenshot for parameter selection, providing specific verb and resource.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context: before using take_screenshot to select a monitor. It does not explicitly state when not to use it or alternatives, but the intended use case is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
截取屏幕并返回图片，用于查看自己刚产出的真实画面（前端页面、EDA/CAD 图等）。
Args: monitor: 0=所有显示器拼接（默认），1..N=指定单个显示器。 不确定编号时先调 list_monitors。
| Name | Required | Description | Default |
|---|---|---|---|
| monitor | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It states capture and return image, but lacks details on permissions, scope (full screen vs window), or destructiveness. The implicit read-only nature is not explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is brief with no fluff. Purpose is stated upfront, and parameter details are in a clear list. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description covers purpose, parameter usage, and sibling reference. Could mention default behavior more explicitly, but adequate overall.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter 'monitor' is explained with clear semantics (0 for all, positive for single) and a practical tip to call list_monitors. This adds significant value beyond the bare schema (0% coverage).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (capture screen) and resource (screen), and provides context (viewing produced output like UI or CAD). It also distinguishes from sibling tool list_monitors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes when to use (after producing output) and gives explicit guidance on using list_monitors when uncertain about monitor numbers. Does not specify when not to use, but is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0list_monitorstake_screenshotScored across 2 tools
The two tools have clearly distinct purposes: one lists available monitors, the other takes screenshots. There is no overlap or ambiguity.
Both tools use consistent snake_case naming (list_monitors, take_screenshot), following a clear verb_noun pattern.
With only 2 tools, the server is minimal but well-scoped for its specific purpose of screenshot feedback. It is on the lower end of the ideal range but not inappropriate.
The tool set covers the essential workflow: checking available monitors and taking screenshots. No obvious gaps for the stated use case.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Browser-backed QA with evidence and fix-ready reports for coding agents.
Comment on AI-generated webpages; feedback flows back to your coding agent. Free, MIT, local-first.
Generate images, GIFs, and PDFs from HTML, URLs, or templates — from your AI agent.
Screenshot, diff, audit and sitemap-capture any web page — 5 MCP tools for AI agents.
