Skip to main content
Glama

clipboard-vision-mcp

🇫🇷 提供法语版本 → README.fr.md

为 Opencode (DeepSeek V4, GLM 5.1) 中的纯文本模型添加视觉能力 — 直接查看剪贴板中的图像,无需手动保存文件。

已在 Windows 11 + Opencode + DeepSeek V4 Pro 上测试。 支持多操作系统剪贴板(Windows / macOS / Linux X11 / Linux Wayland)。

派生自 itcomgroup/vision-mcp-server — 围绕“剪贴板优先”工具、安全加固、跨平台剪贴板提取以及一键式 AI 安装进行了重写。


问题所在

像 DeepSeek V4 和 GLM 5.1 这样廉价/快速的纯文本模型非常适合处理代码,但它们无法读取图像。每次粘贴截图时,模型都会要求你将其保存到磁盘并提供路径。

Related MCP server: visual-understand-mcp

解决方案

此 MCP 服务器公开了 *_from_clipboard 工具。当 LLM 需要查看你的截图时,它会调用 analyze_clipboard — 服务器读取剪贴板图像,将其发送到真实的视觉模型 (Groq + Llama-4 Scout,免费层级),并返回文本模型可以理解的文本描述。

结果:粘贴 → 提问 → 完成。 无需文件搬运。


🤖 通过 AI 一键安装(推荐)

无需手动执行以下步骤,只需将以下提示词之一粘贴到任何编码助手(DeepSeek、GLM、Claude、GPT 等)中,它就会为你完成所有设置 — 克隆、虚拟环境、依赖项、MCP 配置、快捷键:

更喜欢自己动手?请继续阅读。


功能特性

  • 🖼️ 剪贴板优先 — analyze_clipboard、extract_text_from_clipboard、diagnose_error_from_clipboard、describe_ui_from_clipboard、code_from_clipboard。

  • 📁 文件路径回退 — 同样的工具也适用于磁盘上已有的图像。

  • 🆓 免费视觉后端 — Groq 的免费层级,提供 Llama-4 Scout (17B, 多模态)。

  • 🖥️ 多操作系统 — Windows、macOS、Linux (X11 + Wayland)。

  • 🔒 安全加固 — 扩展名/大小/魔数验证,分析后自动删除剪贴板临时文件。

  • 🔌 MCP 标准 — 适用于 Opencode、Claude Code、Cursor、Cline、Continue 或任何支持 MCP 的客户端。


要求

  • Python 3.10+

  • Groq API 密钥(免费,30 秒注册):https://console.groq.com/keys

  • 支持 MCP 的客户端(Opencode、Claude Code、Cursor、Cline、Continue 等)

Python 依赖项(通过 pip install -e . 自动安装)

包

用途

mcp>=1.0.0

MCP 协议服务器

groq>=0.11.0

Groq API 客户端 (Llama-4 Scout 视觉)

aiofiles>=23.0.0

异步文件 I/O

Pillow>=10.0.0

剪贴板图像提取 (Windows/macOS), PNG 编码

操作系统特定的剪贴板依赖项

操作系统

命令

原因

Windows

无需额外操作

Pillow + pywin32 原生处理剪贴板。

macOS

brew install pngpaste (可选回退)

Pillow 在大多数情况下有效;pngpaste 作为备份。

Linux — Wayland

sudo apt install wl-clipboard

提供 wl-paste。

Linux — X11

sudo apt install xclip

或你发行版对应的等效命令。


快速入门

1. 获取免费的 Groq API 密钥

https://console.groq.com/keys

2. 安装

git clone https://github.com/Capetlevrai/clipboard-vision-mcp.git
cd clipboard-vision-mcp
python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate
pip install -e .

3. 冒烟测试(无需 Groq)

复制任意截图,然后:

python examples/smoke_test.py

预期结果:OK: clipboard image saved to <path>。

4. 连接到你的 MCP 客户端

查看 docs/OPENCODE.md 了解 Opencode(已在 Windows 测试),或查看 docs/CLIENTS.md 了解 Claude Code / Cursor / Cline / Continue。

Opencode (%APPDATA%\opencode\opencode.json (Windows), ~/.config/opencode/opencode.json (Linux/macOS)):

{
  "mcp": {
    "clipboard-vision": {
      "type": "local",
      "command": [
        "C:\\path\\to\\clipboard-vision-mcp\\.venv\\Scripts\\python.exe",
        "-m",
        "clipboard_vision_mcp"
      ],
      "enabled": true,
      "environment": {
        "GROQ_API_KEY": "gsk_your_key_here"
      }
    }
  }
}

💡 使用虚拟环境 Python 的绝对路径。 这能确保 MCP 无论在什么 shell、当前工作目录或激活的虚拟环境下都能以正确的依赖项启动。

5. ⚠️ Opencode 粘贴图像的快捷键

Opencode 默认不将图像粘贴绑定到 Ctrl+V / Alt+V。如果不执行此步骤,复制截图并点击粘贴将不会插入任何内容(或仅插入纯文本)。

编辑你的 Opencode keybinds.json 或 opencode.json 中的 keybinds 部分:

{
  "keybinds": {
    "input_paste": "ctrl+v",
    "input_paste_image": "alt+v"
  }
}

编辑后重启 Opencode。

6. Windows 重启后会自动启动吗?

是的。 Opencode 在每次启动时都会重新读取 opencode.json,并自动生成任何 "type": "local" 且 "enabled": true 的 MCP 服务器。由于命令使用了虚拟环境 Python 的绝对路径,因此 Opencode 从哪个 shell 或工作目录启动并不重要。

重启 → 打开 Opencode → 列出 clipboard-vision 工具。无需手动步骤。


使用方法

You: (copy a screenshot to clipboard, then type)
     "Look at what I just copied and tell me what's wrong with this error."

LLM (DeepSeek, GLM, Claude, ...): [calls diagnose_error_from_clipboard]
     → "The error says `ECONNREFUSED 127.0.0.1:5432`. Postgres isn't
        running on port 5432. Start it with: ..."

纯文本模型永远看不到像素 — 它读取 Llama-4 Scout 返回的描述并进行推理。

工具参考

工具

输入

使用场景

analyze_clipboard

可选 prompt

通用描述,对剪贴板图像进行问答。

extract_text_from_clipboard

—

纯 OCR。

describe_ui_from_clipboard

—

UI/UX 审查,组件清单。

diagnose_error_from_clipboard

—

错误截图 → 原因 + 修复。

code_from_clipboard

—

从截图中提取代码。

analyze_image

image_path, 可选 prompt

磁盘上已有的图像。

extract_text, describe_ui, diagnose_error, understand_diagram, analyze_chart, code_from_screenshot

image_path

同上,针对文件。


安全性

此服务器作为本地 stdio 进程运行 — 它不打开任何网络端口,仅通过 stdin/stdout 与 MCP 客户端通信,并通过 HTTPS 与 Groq API 通信。

已实施的加固措施:

  • 文件类型允许列表。 analyze_image 和其他文件路径工具仅接受 .png .jpg .jpeg .gif .webp .bmp。这防止了提示词注入的 LLM 要求服务器读取任意本地文件(~/.ssh/id_rsa、.env 等)并将其作为 base64 泄露给 Groq。

  • 魔数检查。 上传前会根据已知的图像头验证文件内容。

  • 大小限制。 每张图像最大 20 MB。

  • 自动删除剪贴板临时文件。 每次分析后删除。截图可能包含机密信息(令牌、聊天记录、凭据)— 服务器将其写入 $TMPDIR/clipboard_vision_mcp/ 并在完成后取消链接。

  • 无遥测。 无分析,无回传。

此项目无法保护你的方面

  • 你的 API 密钥以明文形式存储在 MCP 客户端配置中。 这就是目前 MCP 客户端的工作方式。请确保该配置文件不可被他人读取,且永远不要提交到版本控制中。如果你不小心泄露了密钥(聊天、截图、git 推送),请在 https://console.groq.com/keys 处轮换密钥。

  • Groq 会接收你分析的图像。 在发送任何敏感内容之前,请查看他们的 隐私政策。

  • 任何 MCP 工具都是在 LLM 的指令下执行的。 如果你将一个被提示词注入的模型连接到此服务器并输入不受信任的内容,模型可以选择要分析的内容。上述允许列表减少了影响范围,但无法完全消除。

发现问题?

请提交 私有安全建议,而不是公开问题。


工作原理

┌──────────────┐   MCP   ┌─────────────────┐   HTTPS   ┌─────────────────┐
│  Opencode    │ ──────▶ │  clipboard-     │ ────────▶ │  Groq API       │
│  (DeepSeek)  │         │  vision-mcp     │           │  Llama-4 Scout  │
└──────────────┘         └─────────────────┘           └─────────────────┘
                              │
                              ▼
                     reads system clipboard
                     (PIL / wl-paste / xclip)
                     → validate → base64 → send → delete

故障排除

  • "Clipboard does not contain an image." — 复制真实的图像,而不是文件图标或文本。在 Linux 上,验证 wl-paste --type image/png 或 xclip -selection clipboard -t image/png -o | file - 在 MCP 之外是否有效。

  • "GROQ_API_KEY is not set." — 检查客户端配置中的 environment 块,然后完全重启客户端。

  • 工具未在 Opencode 中显示。 — 检查 Opencode 的 MCP 日志。手动运行 python -m clipboard_vision_mcp — 它应该启动并静默等待 stdin。

  • "Refusing to read '' — only image files are allowed." — 你(或 LLM)传递了一个非图像路径。这是安全防护在发挥作用。


致谢

许可证

MIT — 参见 LICENSE。

Available Tools

12 tools
analyze_chartC

Analyze a chart image file.

Inputs: image_path (required).

analyze_clipboardA

Read the image currently in the system clipboard and analyze it. Use this when the user says 'look at this', 'what's in my clipboard', or pastes a screenshot without providing a file path. Optional prompt overrides the default description request.

Inputs: prompt.

analyze_imageC

Analyze an image file. Provide image_path and optional prompt.

Inputs: image_path (required), prompt.

code_from_clipboardB

Extract code from a clipboard screenshot, identifying the language.

Inputs: no named parameters.

code_from_screenshotB

Extract code from a screenshot file.

Inputs: image_path (required).

describe_uiC

Describe a UI screenshot file.

Inputs: image_path (required).

describe_ui_from_clipboardA

Describe the UI in a clipboard screenshot (layout, components, state).

Inputs: no named parameters.

diagnose_errorC

Diagnose an error screenshot file.

Inputs: image_path (required).

diagnose_error_from_clipboardB

Diagnose an error screenshot from the clipboard and propose fixes.

Inputs: no named parameters.

extract_textC

OCR an image file.

Inputs: image_path (required).

extract_text_from_clipboardA

OCR the image currently in the clipboard and return only its text.

Inputs: no named parameters.

understand_diagramC

Interpret a diagram image file.

Inputs: image_path (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 12 tools

    Disambiguation4/5

    Tools are mostly distinct, but analyze_clipboard (general clipboard analyzer) overlaps with specialized clipboard tools like code_from_clipboard and describe_ui_from_clipboard, potentially confusing an agent about which to use for a broad request.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern (e.g., analyze_chart, extract_text, describe_ui_from_clipboard), with predictable suffixes for clipboard variants.

    Tool Count5/5

    12 tools is a well-scoped count for an image analysis server covering both file and clipboard inputs for common specialized tasks (text, code, UI, errors, diagrams) plus general analysis.

    Completeness4/5

    The set covers most common image analysis needs, but lacks clipboard-specific tools for chart and diagram analysis (only file versions exist), leaving a minor gap that the general analyze_clipboard can fill but with less specificity.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers