Snipaya

snipaya-mcp

将任何支持 stdio 的 MCP 客户端连接到 Snipaya，这是一款适用于 macOS 的图像和屏幕截图标注工具。助手可以读取画布、添加箭头、文本、形状和标注，遮盖敏感数据、裁剪并导出，同时你可以在 Snipaya 中查看结果。

Snipaya 内置了一个通过 Streamable HTTP 在 127.0.0.1 上提供服务的 MCP 服务。snipaya-mcp 是一个轻量桥接程序，供只能启动本地 stdio 服务的客户端使用：它会在客户端与 Snipaya 之间原样转发每条 MCP 消息。

即使 Snipaya 尚未打开，工具和提示词也会列出。在 Snipaya 响应之前，桥接程序会从内置目录中列出这些内容，并在调用工具时返回一条说明后续操作的消息。

已收录于 MCP Registry，条目为 io.github.krzysztofsurdy/snipaya-mcp；也已收录于 Glama 和 TensorBlock awesome-mcp-servers。

要求

• 适用于 macOS 的 Snipaya。附带 14 天免费试用。
• Node.js 20 或更高版本（用于 npx 配置）。

在 Snipaya 中启用 MCP 服务

该服务默认处于关闭状态。

1. 打开 Snipaya，然后选择 设置 > AI 助手。
2. 开启 允许 AI 助手。状态将变为 运行中。

桥接程序只需这些设置。它会从 Snipaya 保存在这台 Mac 上的设置中读取访问令牌和端口，因此你无需手动复制。

配置

npx

npx -y snipaya-mcp

如果 Snipaya 尚未运行，但已开启 允许 AI 助手，桥接程序会在后台打开 Snipaya，并最多等待 10 秒以启动其服务。

如需覆盖 Snipaya 保存的设置，请设置以下变量或标志。标志优先级高于变量，变量优先级高于已保存的设置。

变量	标志	默认值
SNIPAYA_MCP_TOKEN	--token	Snipaya 保存的令牌	设置 > AI 助手中的访问令牌。
SNIPAYA_MCP_URL	--url	http://127.0.0.1:<saved port>/mcp，否则为 http://127.0.0.1:47321/mcp	Snipaya 的服务 URL。只接受 127.0.0.1 和 localhost。
SNIPAYA_MCP_NO_LAUNCH			设置为 1 可阻止打开 Snipaya。Snipaya 关闭时，工具调用将返回 Cannot reach Snipaya。

建议使用环境变量，而非 --token：Mac 上的其他进程可以看到命令行标志。

JSON 配置

对于使用 mcpServers JSON 文件配置的客户端：

{
  "mcpServers": {
    "snipaya": {
      "command": "npx",
      "args": ["-y", "snipaya-mcp"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org/"
      }
    }
  }
}

如需自定义配置，请改为在 env 中传入这些值：

{
  "mcpServers": {
    "snipaya": {
      "command": "npx",
      "args": ["-y", "snipaya-mcp"],
      "env": {
        "npm_config_registry": "https://registry.npmjs.org/",
        "SNIPAYA_MCP_TOKEN": "<access token>",
        "SNIPAYA_MCP_URL": "<server url>"
      }
    }
  }
}

如果你的客户端直接支持 Streamable HTTP 服务，则无需使用此桥接程序：请改用 Snipaya 中的 复制 MCP 配置。

MCP Bundle（.mcpb）

1. 从最新版本下载 snipaya-mcp-<version>.mcpb。
2. 使用支持 MCP Bundles 的 MCP 客户端打开，或将它拖入客户端的扩展设置中。
3. 留空令牌和 URL 即可使用 Snipaya 保存的设置；如需自定义设置，请粘贴 Settings > AI Assistants 中的值。

安全模型

• 仅限本地。 Snipaya 的服务监听 127.0.0.1，只接受 Host 标头为回环地址且请求不含 Origin 标头的请求，因此浏览器中的网站无法访问它。桥接程序会拒绝主机不是 127.0.0.1 或 localhost 的任何 URL，并且绝不会发送 Origin 标头。
• 默认关闭。 只有启用 Allow AI assistants 后才会开始监听。
• 令牌。 每个请求都会携带 Authorization: Bearer <token>。令牌由 Snipaya 生成，在 Settings 中点击 Regenerate 会使旧令牌失效。桥接程序绝不会将令牌写入日志。
• 已保存的设置。 未设置 SNIPAYA_MCP_TOKEN 时，桥接程序会从 ~/Library/Application Support/Snipaya/mcp.json 读取令牌和端口；该文件由 Snipaya 写入，且仅对你的 macOS 用户可读。桥接程序绝不会写入该文件。
• 打开 Snipaya。 仅限 macOS，且只有在启用 Allow AI assistants 时，桥接程序才会先发送一个不带令牌的请求，以检查 Snipaya 是否有响应。如果连接被拒绝，它会运行 open -g -b dev.snipaya.app（不使用 shell）并重试。启动时会执行此操作；当 Snipaya 不可访问时，工具调用也会再次执行。其他任何错误（例如令牌被拒绝）都不会打开应用。设置 SNIPAYA_MCP_NO_LAUNCH=1 可关闭此功能。
• 桥接程序只负责转发。 它本身不运行任何工具、不存储任何内容，且只连接到 Snipaya。Snipaya 不可访问时，它会根据软件包内置的目录返回工具和提示词列表。所有操作都在 Snipaya 内执行；Snipaya 会在 Settings > AI Assistants 中显示已连接的助手和近期活动。

工具

工具取决于你安装的 Snipaya 版本。在 Snipaya 响应之前，桥接程序会从其目录中列出 Snipaya 1.3.3 的工具；Snipaya 响应后，则会使用你所安装版本的工具列表。Snipaya 1.3 提供：

工具	标题
snipaya_get_canvas	获取画布
snipaya_render	渲染画布
snipaya_add_image	添加图像
snipaya_add_arrow	添加箭头或线条
snipaya_add_shape	添加形状
snipaya_add_text	添加文本
snipaya_add_step	添加步骤编号
snipaya_add_emoji	添加表情符号
snipaya_add_freehand	添加手绘笔画
snipaya_add_magnifier	添加放大镜
snipaya_add_callout	添加标注
snipaya_add_spotlight	添加聚光效果
snipaya_add_measure	添加测量标记
snipaya_pick_color	选取颜色
snipaya_read_text	读取文本
snipaya_redact	遮盖敏感数据
snipaya_update_items	更新元素
snipaya_delete_items	删除元素
snipaya_select	选择元素
snipaya_arrange	排列图像
snipaya_set_crop	设置裁剪
snipaya_undo	撤销
snipaya_redo	重做
snipaya_tabs	管理标签页
snipaya_export	导出图像
snipaya_list_destinations	列出导出目标位置
snipaya_export_to	导出到目标位置
snipaya_save_project	保存项目

提示词

提示词	标题	可选参数
explain_bug	解释截图中的错误	issue
redact_before_sharing	分享前遮盖机密信息	also_hide
finish_screenshot	润色截图，使其看起来完整	background
copy_text	从图像中复制文本	area
make_walkthrough	将截图整理成操作指南	topic
compare_before_after	比较更改前后	change

故障排除

桥接程序会将问题写入 stderr（绝不会写入承载协议的 stdout）。Snipaya 无法访问时，它仍会列出工具，并将相同文本作为每次工具调用的结果返回。Snipaya 开始响应后（例如，打开 Snipaya 或接受许可协议后），下一次工具调用即可连接到它，无需重启。

消息	解决方法
Snipaya's settings were not found	安装 Snipaya，打开一次并启用 Allow AI assistants。或者设置 SNIPAYA_MCP_TOKEN。
Snipaya is a macOS app	桥接程序在另一台系统上运行。它会列出工具，但这些工具只能与 Mac 上的 Snipaya 配合使用。
Snipaya's MCP server is off	在 Settings > AI Assistants 中启用 Allow AI assistants。
Snipaya's settings ... cannot be read 或 hold no valid token	打开 Snipaya，让它重新写入设置，然后检查 Allow AI assistants。或者设置 SNIPAYA_MCP_TOKEN。
Cannot open Snipaya	Snipaya 未安装在 macOS 可以找到的位置。请从 snipaya.app 安装，或自行打开它。
Opened Snipaya, but its MCP server starts only after you accept the license agreement	Snipaya 1.1 及更高版本只会在你接受许可协议后启动 MCP 服务。请在 Snipaya 窗口中接受协议，然后再次调用工具。
Opened Snipaya, but its MCP server did not answer	打开 Settings > AI Assistants，并修复状态下方显示的错误。
Cannot reach Snipaya at ...	打开 Snipaya 并启用 Allow AI assistants。如果消息提到许可协议，请先在 Snipaya 中接受协议。如果状态显示错误，请先修复错误。检查 URL 是否与 Server URL 一致。
Snipaya rejected the token	令牌已更改，例如在使用 Regenerate 后。移除 SNIPAYA_MCP_TOKEN 以使用已保存的令牌，或复制当前令牌。
Snipaya ended the session	Snipaya 已重启或令牌已更改。请在客户端中重启 snipaya 服务。
Refusing <host>	URL 必须指向 127.0.0.1 或 localhost。请从 Snipaya 复制 Server URL。
MCP 日志中出现 CONNECTION_CLOSED 或 Failed to connect，并伴有 npm error 404 ... is not in this registry	桥接程序未能启动：项目 .npmrc 将 npm 指向了私有注册表，而 MCP 客户端会在项目文件夹中启动服务。请在 env 中为 snipaya 服务设置 npm_config_registry 为 https://registry.npmjs.org/，如上方 JSON 配置所示。在 Claude Code 中，每个项目都要使用 claude mcp add --scope user snipaya -e npm_config_registry=https://registry.npmjs.org/ -- npx -y snipaya-mcp 添加一次服务。Claude Code 会将 MCP 服务日志保存在 ~/Library/Caches/claude-cli-nodejs/<project>/mcp-logs-snipaya/ 中。

运行 npx -y snipaya-mcp --help 查看选项。

开发

npm ci
npm run lint
npm run typecheck
npm test          # builds, then runs the bridge over stdio against a local test server
npm run pack:mcpb # builds snipaya-mcp-<version>.mcpb with the official mcpb CLI

目录

catalog.json 包含桥接程序在 Snipaya 无法访问时提供的工具、提示词和说明，而 manifest.json 列出相同的工具和提示词。使用 Node 22.6 或更高版本，从 Snipaya 应用的检出目录（默认是 ../snipaya）重新生成这两个文件，并提交结果：

npm run sync:catalog -- ../snipaya

没有令牌或 URL 时，桥接程序会读取已安装 Snipaya 在 ~/Library/Application Support/Snipaya 中的设置。Snipaya 的开发版本会将设置保存在自己的 Snipaya Dev 配置文件夹中，因此若要桥接到该版本，请将 SNIPAYA_MCP_TOKEN 和 SNIPAYA_MCP_URL 设置为其 Settings > AI Assistants 中显示的值。

发布

推送 v* 标签会运行 .github/workflows/release.yml。该工作流会运行 CI 检查，确认标签与 package.json、package-lock.json、server.json 和 manifest.json 中的版本一致，将版本上传到 npm 暂存环境（附带来源证明），最多等待 60 分钟，供维护者审批，然后创建附带 .mcpb 的 GitHub 发布版本，并将 server.json 发布到 MCP Registry。

一次性设置

在 npmjs.com 上，打开 snipaya-mcp > Settings > Trusted publishing，选择 GitHub Actions 并填写：

Field	Value
组织或用户	krzysztofsurdy
仓库	snipaya-mcp
工作流文件名	release.yml
环境名称	留空
允许的操作	仅限 npm stage publish

如果受信任的发布者在 2 天内没有发布，npm 会将其过期，因此请在首次发布前不久添加。MCP Registry 和 GitHub 发布版无需设置：它们使用工作流自身的 GitHub 令牌。

发布新版本

npm version minor        # or patch, major: bumps all four files, commits and tags v<version>
git push --follow-tags

当工作流运行到 Publish to npm 时，使用 2FA 提示批准暂存的版本：npm stage approve snipaya-mcp@<version>，或在 npmjs.com 的软件包页面上批准。其余发布流程会自动继续。

重新运行失败的发布是安全的：如果该版本已存在，则会跳过 npm 和 MCP Registry 发布；如果 GitHub 发布版已存在，则会替换其中的构建包。

许可证

MIT