MCP Screenshot Server

Universal Screenshot MCP

一个 MCP (Model Context Protocol) 服务，为 AI 助手提供截图功能——既可以通过 Puppeteer 捕获网页，也可以使用原生 OS 工具进行跨平台系统截图。

功能

• 网页截图 — 使用无头 Chromium 浏览器捕获任意公开 URL
• 跨平台系统截图 — 使用原生 OS 工具捕获全屏、窗口或区域（macOS screencapture、Linux maim/scrot/gnome-screenshot/等、Windows PowerShell+.NET）
• 安全优先设计 — 防止 SSRF、路径遍历、DNS 重绑定、命令注入和 DoS 攻击
• 原生支持 MCP — 可直接集成到 Claude Desktop、Cursor 和任何兼容 MCP 的客户端

要求

• Node.js >= 18.0.0
• Chromium 会在首次运行时由 Puppeteer 自动下载

take_system_screenshot 的平台特定要求

平台	所需工具	备注
macOS	screencapture（内置）	无需额外安装
Linux	以下工具之一：maim、scrot、gnome-screenshot、spectacle、grim 或 import（ImageMagick）	建议安装 maim 或 scrot 以获得完整功能支持。若要按窗口名称捕获，还需安装 xdotool。
Windows	powershell（内置）	使用 .NET 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 客户端配置中。对于 Claude Desktop，编辑 ~/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 Code，使用 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 查看实时状态。

对于 Cursor 或其他 MCP 客户端，请参阅其文档，了解相应的配置方法。

工具

此服务提供两个 MCP 工具：

take_screenshot

通过无头 Puppeteer 浏览器捕获网页（或特定元素）。

参数	类型	必填	说明
url	string	✅	要捕获的 URL（仅限 http/https）
width	number	—	视口宽度（1–3840）
height	number	—	视口高度（1–2160）
fullPage	boolean	—	捕获完整的可滚动页面
selector	string	—	用于捕获特定元素的 CSS 选择器
waitForSelector	string	—	捕获前等待此选择器
waitForTimeout	number	—	延迟时间，单位为毫秒（0–30000）
outputPath	string	—	输出文件路径（默认：~/Documents/screenshots）

提示词示例：

对 https://example.com 进行截图，分辨率为 1920x1080

take_system_screenshot

使用原生操作系统工具截取桌面、特定应用程序窗口或屏幕区域。支持 macOS、Linux 和 Windows。

Parameter	Type	Required	Description
mode	enum	✅	fullscreen、window 或 region
windowId	number	—	窗口模式下的窗口 ID
windowName	string	—	窗口模式下的应用名称（例如 "Safari"、"Firefox"）
region	object	—	区域模式下的 { x, y, width, height }
display	number	—	多显示器配置下的显示器编号
includeCursor	boolean	—	是否在截图中包含鼠标光标
format	enum	—	png（默认）或 jpg
delay	number	—	截图延迟秒数（0–10）
outputPath	string	—	输出文件路径（默认：~/Documents/screenshots）

跨平台功能支持

Feature	macOS	Linux	Windows
全屏	✅	✅	✅
区域	✅	✅ (maim, scrot, grim, import)	✅
按名称选择窗口	✅	⚠️ X11 + xdotool	⚠️ 尽力支持
按 ID 选择窗口	✅	✅ 仅限 X11	⚠️ HWND
多显示器	✅	⚠️ 取决于工具	✅
包含光标	✅	⚠️ 取决于工具	⚠️
延迟	✅	✅	✅

提示词示例：

截取 Safari 窗口的系统屏幕截图

配置

环境变量

Variable	Default	Description
SCREENSHOT_OUTPUT_DIR	Documents/screenshots	相对于 ~ 的默认输出目录
ALLOW_LOCAL	false	设置为 true，以允许截取 localhost/127.x.x.x/[::1] 的屏幕截图（适用于本地开发服务器）

输出目录

屏幕截图默认保存到 ~/Documents/screenshots（可通过 SCREENSHOT_OUTPUT_DIR 配置）。自定义输出路径必须解析到以下允许的目录之一：

Directory	Description
~/Documents/screenshots	默认输出位置（可配置）
~/Desktop/Screenshots	原默认位置
~/Downloads	用户下载文件夹
~/Documents	用户文档文件夹
/tmp	系统临时目录

安全

此服务采用多层安全加固措施：

ID	Threat	Mitigation
SEC-001	SSRF / DNS 重绑定	根据被阻止的 IP 地址范围验证 URL；请求前解析 DNS，并通过 --host-resolver-rules 固定 IP；重新验证导航重定向
SEC-003	命令注入	所有子进程均使用 execFile（不使用 shell）；根据 SAFE_APP_NAME_PATTERN 验证应用名称
SEC-004	路径遍历	使用 fs.realpath() 解析符号链接并验证输出路径；限制在允许的目录中
SEC-005	拒绝服务	通过信号量将并发 Puppeteer 实例限制为 3

完整详情请参阅 docs/security.md。

开发

脚本

命令	说明
npm run build	将 TypeScript 编译到 build/
npm run watch	文件更改时重新编译
npm test	单元测试（快速，完全模拟）
npm run test:integration	集成测试（使用真实 DNS／文件系统）
npm run test:e2e	端到端测试（使用真实 Puppeteer／原生工具）
npm run test:all	一并运行所有测试层级
npm run test:linux	通过 Docker 运行 Linux 端到端测试（需要 Docker）
npm run test:watch	在监视模式下运行测试
npm run test:coverage	运行测试并生成覆盖率报告
npm run lint	使用 ESLint 检查源代码
npm run inspector	启动 MCP Inspector 以进行调试

项目结构

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)

测试

测试使用 Vitest，分为三个层级：

• 单元测试（npm test）—— 完整的依赖注入，不进行真实 I/O。反馈周期快。
• 集成测试（npm run test:integration）—— 进行真实 DNS 解析，使用临时目录操作真实文件系统，并通过本地 HTTP 服务运行真实 Puppeteer。
• 端到端测试（npm run test:e2e）—— 使用真实的原生截图工具。macOS 测试原生运行；Linux 测试通过 npm run test:linux 在 Docker 中运行。

npm test                 # Unit tests (~300ms)
npm run test:linux       # Linux provider tests in Docker
npm run test:all         # Everything

使用 MCP Inspector 调试

npm run inspector

此命令会启动 MCP Inspector，并连接到已构建的服务，以便交互式调用工具。

许可证

Apache-2.0 — 版权所有 2026 Seth Bang