ClipGrab

ClipGrab

mcp-name: io.github.ulebule/clipgrab

一个 MCP 服务，用于将系统剪贴板中的当前图像保存为文件（PNG 或 JPG）。

原因

许多 AI Agent 可以读取图像文件，但无法访问系统剪贴板。ClipGrab 填补了这一空白：复制图像（例如屏幕截图），调用工具，即可获取已保存到磁盘上的图像路径，供 Agent 打开。

默认情况下，图像会保存到当前工作目录，也就是 Agent 运行所在的文件夹。

要求

• Python 3.10+
• Python 包（见 requirements.txt）：Pillow、mcp[cli]
• 仅限 Linux：剪贴板回退方案需要 wl-clipboard（wl-paste）或 xclip。

从 PyPI 安装

使用 uv 直接运行（无需安装步骤）：

uvx clipgrab-mcp

或使用 pip 安装：

pip install clipgrab-mcp
clipgrab-mcp

从源代码设置

python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt

工具

• save_clipboard_image(directory?, filename?, image_format?) → 保存剪贴板图像并返回绝对路径。
  • directory — 默认为当前工作目录（如不存在则创建）。 也可以通过 CLIPGRAB_DEFAULT_DIR 环境变量设置。
  • filename — 默认为带时间戳的名称（clipboard-YYYYMMDD-HHMMSS）。
  • image_format — "png"（默认）或 "jpg"。
• clipboard_has_image() → 返回 true/false。

手动运行（stdio）

./.venv/bin/python mcp_server.py

安装为 VS Code 扩展

ClipGrab 以 VS Code 扩展的形式发布，可自动注册 MCP 服务 — 随后它会显示在扩展视图 → MCP 服务下，并按需启动。首次使用时，扩展会创建自己的 Python 虚拟环境并安装依赖，因此你只需要在 PATH 中配置 Python 3.10+（可通过 clipgrab.pythonPath 设置项进行配置）。

开发 / 试用：

1. 在 VS Code 中打开此文件夹，然后按 F5 启动扩展开发主机。
2. 在该窗口中打开聊天（Agent 模式）；即可使用 ClipGrab MCP 服务及其 save_clipboard_image 工具。

打包 .vsix 以供分享：

npm install -g @vscode/vsce
vsce package

VS Code 配置（不使用扩展）

可直接使用的配置位于 .vscode/mcp.json：

{
  "servers": {
    "clipgrab": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/mcp_server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}

然后打开 .vscode/mcp.json 并启动 clipgrab 服务（或使用命令面板 →“MCP: List Servers”）。

与 MCP 客户端搭配使用

通过 stdio 将任意 MCP 客户端指向已发布的 PyPI 包：

{
  "servers": {
    "clipgrab": {
      "command": "uvx",
      "args": ["clipgrab-mcp"]
    }
  }
}

server.json 中包含 ClipGrab 的注册表描述；该项目以 io.github.ulebule/clipgrab 的名称发布到 官方 MCP 注册表。

技术说明

• 跨平台图像抓取：使用 Pillow 的 ImageGrab.grabclipboard()（适用于 Windows / macOS，也适用于使用较新版本 Pillow 的 Linux）。在 Linux 上，会回退到 wl-paste / xclip。

许可证

MIT