使用说明
通用屏幕截图MCP
一 MCP（模型上下文协议） 为AI助手提供屏幕截图功能的服务器——通过 操纵者 以及使用本地操作系统工具的跨平台系统截图。
特性
- 网页截图 --使用无头Chromium浏览器捕获任何公共URL
- 跨平台系统截图 --使用本机操作系统工具（macOS）进行全屏、窗口或区域捕获
screencapture，Linuxmaim/scrot/gnome-screenshot/等等。，Windows PowerShell+。NET） - 安全第一设计 --SSRF防护、路径遍历防护、DNS重新绑定防护、命令注入防护和DoS限制
- MCP本地 --直接与Claude Desktop、Cursor和任何兼容MCP的客户端集成
需求
- Node.js >= 18.0.0
- 铬 首次运行时由Puppeteer自动下载
平台特定要求 take_system_screenshot
| 平台 | 所需工具 | 注意事项 |
|---|---|---|
| macOS | screencapture （内置） |
无需额外安装 |
| Linux | 其中之一： maim, scrot, gnome-screenshot, spectacle, grim，或 import （ImageMagick） maim 或 scrot 建议使用完整功能支持。对于按名称捕获窗口，也要安装 xdotool. |
|
| 视窗 | powershell （内置） |
用途。网 System.Drawing --无需额外安装 |
Linux安装示例
# Ubuntu/Debian (recommended)
sudo apt install maim xdotool
# Fedora
sudo dnf install maim xdotool
# Arch Linux
sudo pacman -S maim xdotool
# Wayland (Sway, etc.)
sudo apt install grim
安装后，您可以通过以下方式验证您的设置：
npx universal-screenshot-mcp --doctor
这会探测主机并打印可复制粘贴的安装命令，以查找任何缺失的工具，这些工具是根据您检测到的发行版量身定制的。
快速开始
从npm安装
npm install -g universal-screenshot-mcp
或者直接与 npx:
npx universal-screenshot-mcp
从源代码安装
git clone https://github.com/sethbang/mcp-screenshot-server.git
cd mcp-screenshot-server
npm install
npm run build
配置您的MCP客户端
将服务器添加到MCP客户端配置中。对于 克劳德桌面版，编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"screenshot-server": {
"command": "npx",
"args": ["-y", "universal-screenshot-mcp"]
}
}
}
或者，如果从源代码安装：
{
"mcpServers": {
"screenshot-server": {
"command": "node",
"args": ["/absolute/path/to/mcp-screenshot-server/build/index.js"]
}
}
}
对于 克劳德代码，向注册服务器 claude mcp add 命令：
# Project scope (current directory only)
claude mcp add screenshot-server -- npx -y universal-screenshot-mcp
# User scope (available across all projects)
claude mcp add --scope user screenshot-server -- npx -y universal-screenshot-mcp
或者，如果从源代码安装：
claude mcp add screenshot-server -- node /absolute/path/to/mcp-screenshot-server/build/index.js
验证已注册的服务器 claude mcp list，或从会话内部检查实时状态 /mcp.
对于 光标 或其他MCP客户端，请查阅其文档以获取等效配置。
工具
服务器公开了两个MCP工具：
take_screenshot
通过无头Puppeteer浏览器捕获网页（或特定元素）。
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
url |
string | ✅ | 要捕获的URL（仅限http/https） |
width |
数字 | -- | 视口宽度（1–3840） |
height |
数字 | -- | 视口高度（1–2160） |
fullPage |
boolean | -- | 捕获整个可滚动页面 |
selector |
string | -- | CSS选择器，用于捕获特定元素 |
waitForSelector |
string | -- | 在捕获之前等待此选择器 |
waitForTimeout |
number | -- | 延迟（毫秒）（0-30000） |
outputPath |
string | -- | 输出文件路径（默认值： ~/Documents/screenshots) |
示例提示：
截取以下内容的屏幕截图https://example.com1920x1080
take_system_screenshot
使用本机操作系统工具捕获桌面、特定应用程序窗口或屏幕区域。工作在 macOS, Linux，以及 视窗.
| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
mode |
枚举 | ✅ | fullscreen, window，或 region |
windowId |
number | -- | 窗口模式的窗口ID |
windowName |
string | -- | 应用程序名称（例如。 "Safari", "Firefox")用于窗口模式 |
region |
对象 | -- | { x, y, width, height } 用于区域模式 |
display |
number | -- | 显示多显示器设置的编号 |
includeCursor |
boolean | -- | 在捕获中包含鼠标光标 |
format |
枚举 | -- | png （默认）或 jpg |
delay |
number | -- | 捕获延迟（秒）（0-10） |
outputPath |
string | -- | 输出文件路径（默认值： ~/Documents/screenshots) |
跨平台功能支持
| 功能 | macOS | Linux | Windows |
|---|---|---|---|
| 全屏 | ✅ | ✅ | ✅ |
| 地区 | ✅ | ✅ （残废、阴囊、冷酷、进口） | ✅ |
| 窗口名称 | ✅ | ⚠️ X11+十二醇 | ⚠️ 尽最大努力 |
| 按ID显示窗口 | ✅ | ✅ 仅限X11 | ⚠️ HWND |
| 多显示器 | ✅ | ⚠️ 依赖工具 | ✅ |
| 包含光标 | ✅ | ⚠️ 依赖工具 | ⚠️ |
| 延迟 | ✅ | ✅ | ✅ |
示例提示：
拍摄Safari窗口的系统屏幕截图
配置
环境变量
| 变量 | 默认值 | 描述 |
|---|---|---|
SCREENSHOT_OUTPUT_DIR |
Documents/screenshots |
相对于的默认输出目录 ~ |
ALLOW_LOCAL |
false |
设置为 true 允许进行屏幕截图 localhost/127.x.x.x/[::1] （对本地开发服务器有用） |
输出目录
屏幕截图保存到 ~/Documents/screenshots 默认情况下（可通过配置 SCREENSHOT_OUTPUT_DIR).自定义输出路径必须解析为以下允许的目录之一：
| 目录 | 描述 |
|---|---|
~/Documents/screenshots |
默认输出位置（可配置） |
~/Desktop/Screenshots |
原始默认位置 |
~/Downloads |
用户下载文件夹 |
~/Documents |
用户文档文件夹 |
/tmp |
系统临时目录 |
安全
此服务器实现了多层安全强化：
| ID | 威胁 | 缓解 |
|---|---|---|
| SEC-001 | SSRF/DNS重新绑定 | URL已针对被阻止的IP范围进行验证；DNS通过IP固定解决预请求 --host-resolver-rules；导航重定向已重新验证 |
| SEC-003 | 命令注入 | 所有子流程使用 execFile （无外壳）；应用程序名称已验证 SAFE_APP_NAME_PATTERN |
| SEC-004 | 路径遍历 | 输出路径已通过验证 fs.realpath() 符号链接解析；仅限于允许的目录 |
| SEC-005 | 拒绝服务 | 通过信号量将并发Puppeter实例限制为3个 |
有关完整详细信息，请参阅 docs/security.md.
发展
脚本
| 命令 | 描述 |
|---|---|
npm run build |
将TypeScript编译为 build/ |
npm run watch |
重新编译文件更改 |
npm test |
单元测试（快速、完全模拟） |
npm run test:integration |
集成测试（真实DNS/文件系统） |
npm run test:e2e |
E2E测试（真实的Puppeteer/原生工具） |
npm run test:all |
所有测试层在一起 |
npm run test:linux |
Linux e2e通过Docker（需要Docker） |
npm run test:watch |
在监视模式下运行测试 |
npm run test:coverage |
使用覆盖率报告运行测试 |
npm run lint |
使用ESLint的Lint源代码 |
npm run inspector |
启动MCP检查器进行调试 |
项目结构
src/
├── index.ts # Entry point — stdio transport
├── server.ts # MCP server factory
├── config/
│ ├── index.ts # Static constants (limits, allowed dirs)
│ └── runtime.ts # Singleton semaphore, default directory
├── tools/
│ ├── take-screenshot.ts # Web page capture tool
│ └── take-system-screenshot.ts # macOS system capture tool
├── types/
│ └── index.ts # Shared TypeScript interfaces
├── utils/
│ ├── helpers.ts # Response builders, file utilities
│ ├── screenshot-provider.ts # Cross-platform provider interface + factory
│ ├── macos-provider.ts # macOS: screencapture wrapper
│ ├── linux-provider.ts # Linux: maim/scrot/gnome-screenshot/etc.
│ ├── windows-provider.ts # Windows: PowerShell + .NET System.Drawing
│ ├── macos.ts # Window ID lookup via CoreGraphics
│ └── semaphore.ts # Async concurrency limiter
└── validators/
├── path.ts # Output path validation (SEC-004)
└── url.ts # URL/SSRF validation (SEC-001)
测试
测试使用 维测试 分为三个层次：
- 单元 (
npm test)--完全依赖注入，没有真正的I/O。快速反馈循环。 - 整合 (
npm run test:integration)--真实的DNS解析，带有临时目录的真实文件系统，针对本地HTTP服务器的真实Puppeter。 - E2E (
npm run test:e2e)--真正的本地截图工具。macOS测试本机运行；Linux测试通过Docker运行npm run test:linux.
npm test # Unit tests (~300ms)
npm run test:linux # Linux provider tests in Docker
npm run test:all # Everything
使用MCP检查器进行调试
npm run inspector
这将启动 MCP检查员 连接到您构建的服务器，允许您以交互方式调用工具。
许可证
阿帕奇-2.0 --版权所有2026赛斯邦
