Skip to main content
Glama
deenesjakoruzh
sethbang

MCP Screenshot Server

by sethbang
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

通用截图 MCP

npm version MCP Registry License

一个 MCP (Model Context Protocol) 服务器，为 AI 助手提供截图功能——既包括通过 Puppeteer 进行的网页截图，也包括使用原生操作系统工具进行的跨平台系统截图。

功能特性

  • 网页截图 — 使用无头 Chromium 浏览器捕获任何公共 URL

  • 跨平台系统截图 — 使用原生操作系统工具进行全屏、窗口或区域捕获（macOS screencapture，Linux maim/scrot/gnome-screenshot/等，Windows PowerShell+.NET）

  • 安全优先设计 — 防范 SSRF、路径遍历、DNS 重绑定、命令注入及拒绝服务 (DoS) 限制

  • MCP 原生 — 直接与 Claude Desktop、Cursor 及任何兼容 MCP 的客户端集成

Related MCP server: Chrome DevTools 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。

参数

类型

必需

描述

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)

跨平台功能支持

功能

macOS

Linux

Windows

全屏

✅

✅

✅

区域

✅

✅ (maim, scrot, grim, import)

✅

按名称窗口

✅

⚠️ X11 + xdotool

⚠️ 尽力而为

按 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 范围进行验证；通过 --host-resolver-rules 在请求前解析 DNS 并锁定 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 对源码进行 Lint 检查

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

Available Tools

2 tools
take_screenshotB

Capture web page or element via headless browser. Saves to ~/Documents/screenshots by default (configurable via SCREENSHOT_OUTPUT_DIR env var).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesURL to capture
widthNoViewport width
heightNoViewport height
fullPageNoCapture full page
selectorNoCSS selector for element
waitForSelectorNoWait for selector
waitForTimeoutNoDelay in ms
outputPathNoAbsolute path, or relative to home dir

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden but only mentions method and save location; it omits critical behavioral traits like destructiveness, permission needs, or return value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences: first states purpose, second details save behavior. Front-loaded and no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite 8 parameters and no output schema, the description omits return value, error handling, and other essential context, leaving significant gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers all 8 parameters with descriptions, so baseline is 3. The description adds the default save path and env var override, providing marginal extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'capture' and resource 'web page or element' with method 'via headless browser', clearly distinguishing it from sibling 'take_system_screenshot' which captures system screens.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for web screenshots but does not explicitly state when to use versus alternatives, nor does it mention prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

take_system_screenshotA

Capture desktop, window, or region screenshot. Cross-platform: macOS (screencapture), Linux (maim/scrot/gnome-screenshot/etc.), Windows (PowerShell+.NET). Saves to ~/Documents/screenshots by default (configurable via SCREENSHOT_OUTPUT_DIR env var). For window mode, provide windowName (app name like "Safari") or windowId.

ParametersJSON Schema
NameRequiredDescriptionDefault
modeYesfullscreen=entire screen, window=specific app (requires windowName or windowId), region=coordinates
windowIdNoWindow ID (for window mode)
windowNameNoApp name like "Safari", "Firefox" (for window mode)
regionNoRegion {x,y,width,height}
displayNoDisplay number
includeCursorNoInclude cursor
formatNoImage format (png or jpg)
delayNoDelay seconds
outputPathNoAbsolute path, or relative to home dir

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It discloses the default save location and cross-platform tool dependencies but does not mention return behavior (e.g., file path or binary), permission requirements, or failure modes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with 4 sentences, front-loading the main action. It effectively uses bullet-like information for cross-platform details and mode instructions, though it could be slightly more structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 9 parameters including a nested object and no output schema, the description covers default directory and platform support but omits return value, error handling, and comparison with the sibling tool. It is adequate but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds minor value by specifying default output directory and that windowName is an app name, but the schema already describes all parameters adequately.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Capture desktop, window, or region screenshot' with specific verb and resource. It distinguishes from the sibling tool 'take_screenshot' by specifying cross-platform support and modes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use each mode (fullscreen, window, region) and gives examples for window mode. However, it lacks guidance on when not to use this tool versus the sibling 'take_screenshot', missing explicit exclusion or alternative differentiation.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.2.0
    • Changedtake_screenshot10 fields changed
      • addedInput schema / $schema
        Added value: +"http://json-schema.org/draft-07/schema#"
      • addedInput schema / additionalProperties
        Added value: +false
      • changedInput schema / properties / fullPage / description
        Previous value: -"Capture full scrollable page"New value: +"Capture full page"
      • changedInput schema / properties / height / description
        Previous value: -"Viewport height in pixels"New value: +"Viewport height"
      • changedInput schema / properties / outputPath / description
        Previous value: -"Custom output path (optional)"New value: +"Absolute path, or relative to home dir"
      • addedInput schema / properties / selector
        Added value: +{
+  "description": "CSS selector for element",
+  "type": "string"
+}
      • changedInput schema / properties / url / description
        Previous value: -"URL to capture (can be http://, https://, or file:///)"New value: +"URL to capture"
      • addedInput schema / properties / waitForSelector
        Added value: +{
+  "description": "Wait for selector",
+  "type": "string"
+}
      • addedInput schema / properties / waitForTimeout
        Added value: +{
+  "description": "Delay in ms",
+  "maximum": 30000,
+  "minimum": 0,
+  "type": "number"
+}
      • changedInput schema / properties / width / description
        Previous value: -"Viewport width in pixels"New value: +"Viewport width"
    • Addedtake_system_screenshot
  2. 1 tool update
    • First observedtake_screenshot
Deploy Server
Let your AI agent see the webWeb-to-screenshot MCP for Claude, Cursor and Codex. No cookie banners. Free to start.snap-render.comAd

TDQS

A3.7/5.0

Scored across 2 tools

Disambiguation5/5

The two tools are clearly distinct: one captures web pages/elements via headless browser, the other captures desktop/system screenshots. There is no overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with snake_case (take_screenshot, take_system_screenshot), using the same 'take_' prefix.

Tool Count3/5

Only 2 tools for a screenshot server is minimal but still covers the core use cases. More tools might be expected for management or configuration, but the count is not severely inadequate.

Completeness4/5

The tool set covers the primary screenshot domains (web and system). Minor gaps exist, such as listing or deleting screenshots, but core functionality is well-covered.

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Webshot MCP

    bingal
    A
    license
    C
    quality
    D
    maintenance
    Enables taking screenshots of web pages with support for multiple devices (desktop, mobile, tablet), custom dimensions, full-page capture, and various image formats. Built with Playwright for reliable web page rendering and screenshot generation.
    1
    MIT

  • Screenshot API

    raphy78626
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI agents to capture any public URL as PNG, JPEG, or PDF via REST API or MCP tools, including screenshot capture, page description, and PDF rendering.
    10 npm
    MIT

Appeared in Searches