clipboard-vision-mcp

v0.2.0

Published

16 days ago

Clipboard-first MCP server that gives vision-less LLMs image recognition via OpenAI-compatible vision models.

0High
0Medium
0Low

lysander2026

mcp vision clipboard ocr openai-compatible

clipboard-vision-mcp

中文 | English

给你的编码助手或 AI 工具装上"眼睛"——注册这个 MCP 服务，它就能看懂你剪贴板里的截图。自动把图片发给 OpenAI-compatible 视觉模型，拿回文字描述或对图片问题的回答。

LLM（无视觉）──MCP/stdio──► clipboard-vision-mcp ──OpenAI-compatible API──► 视觉模型 ──► 文本结果

快速开始

1. 准备运行环境

需要 Node.js ≥ 20，以及一个能访问视觉模型的 OpenAI-compatible API key（可在下面的 MCP Host 配置中填入）。这里的 OPENAI_* 变量名只是沿用 OpenAI-compatible 接口习惯，不代表只能使用 OpenAI 官方模型。

最简单的用法是直接在 MCP Host 配置里用 npx -y clipboard-vision-mcp，不需要提前全局安装。想先在本机装好命令，也可以执行：

npm install -g clipboard-vision-mcp

从源码调试时再 clone 仓库运行：

git clone <this-repo> image-recognition-mcp
cd image-recognition-mcp
npm install
npm run build

2. 准备剪贴板工具

系统需要能读取剪贴板中的图片：

macOS：安装 pngpaste（brew install pngpaste）
Windows：系统内置 PowerShell，无需额外安装
Linux Wayland：wl-clipboard 的 wl-paste
Linux X11：xclip

3. 配置 MCP Host

在你的 MCP Host（ZCode、Claude Desktop 等）配置文件中找到 mcpServers 字段，添加以下内容。

下面用 Qwen / DashScope 举例；如果你用 Gemini、LiteLLM、one-api、New API 或其他 OpenAI-compatible 网关，只需要替换 OPENAI_API_KEY、OPENAI_MODEL 和 OPENAI_BASE_URL。

{
  "mcpServers": {
    "clipboard-vision": {
      "command": "npx",
      "args": ["-y", "clipboard-vision-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_MODEL": "qwen-vl-plus",
        "OPENAI_BASE_URL": "https://dashscope.aliyuncs.com/compatible-mode/v1"
      }
    }
  }
}

如果你确实使用 OpenAI 官方接口，可以删掉 OPENAI_BASE_URL，并把模型改成支持视觉的 OpenAI 模型，例如 gpt-4o-mini。

配置路径参考：ZCode 在 ~/.zcode/v2/config.json，Claude Desktop 在 ~/Library/Application Support/Claude/claude_desktop_config.json。

如果从本地 clone 运行，改用 "command": "node"，args 指向 dist/index.js 的绝对路径。

4. 验证

复制一张截图到剪贴板，然后向你的 AI 助手提问：

分析我剪贴板里的截图，上面有什么文字？

如果 MCP Host 已正确加载服务，助手会调用默认读取剪贴板的 recognize_image，然后返回图片内容。

功能

单个通用工具 recognize_image，支持剪贴板、本地文件、URL、data URL 和 base64 图片
通过 prompt 自定义问题，例如描述图片、提取文字或询问截图细节
四种图片来源：剪贴板（默认）、本地文件路径、HTTP(S) URL、base64 / data URL
可配置 OpenAI-compatible provider、模型（默认 gpt-4o-mini）、detail 级别、最大 token 数和超时
发送前校验本地、base64 和剪贴板图片的格式与大小
支持关闭本地文件输入，或用 allowlist 限制可读取的目录
stdio transport，兼容任意 MCP Host

配置项

除在 MCP Host 的 env 中直接设置外，也支持项目根目录的 .env 文件：

cp .env.example .env

服务启动时会自动加载 .env，同时保留 MCP Host 已传入的环境变量。

| 环境变量 | 默认值 | 说明 | | --- | --- | --- | | OPENAI_API_KEY | 必填 | OpenAI-compatible API key | | OPENAI_MODEL | gpt-4o-mini | 视觉模型名 | | OPENAI_BASE_URL | OpenAI 默认地址 | OpenAI-compatible 网关地址；使用 OpenAI 官方时可不填 | | OPENAI_TIMEOUT_MS | 60000 | 请求超时时间（毫秒） | | LOCAL_FILE_INPUT_ENABLED | true | 设为 false 可禁用本地文件路径输入 | | LOCAL_FILE_ALLOWED_ROOTS | 空 | 路径 allowlist，逗号分隔，例如 /tmp,~/Pictures；空表示允许所有路径 |

Provider 示例：

# Qwen / DashScope OpenAI-compatible 端点
OPENAI_API_KEY=...
OPENAI_MODEL=qwen-vl-plus
OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1

# Gemini OpenAI-compatible 端点
OPENAI_API_KEY=...
OPENAI_MODEL=gemini-2.5-flash
OPENAI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai

# LiteLLM 或自托管 OpenAI-compatible 网关
OPENAI_API_KEY=...
OPENAI_MODEL=your-vision-model
OPENAI_BASE_URL=http://localhost:4000/v1

# OpenAI 官方接口
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini

工具说明

`recognize_image`

| 参数 | 类型 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | --- | | image | string | 否 | "clipboard" | 路径 / URL / data URL / base64 / "clipboard" | | prompt | string | 否 | Describe this image in detail, including any visible text. | 对图片的提问或指令 | | detail | "auto" | "low" | "high" | 否 | auto | 视觉 detail 级别，low 更快更省 token | | maxTokens | integer | 否 | 1024 | 响应最大 token 数 |

返回 { content: [{ type: "text", text: "..." }] }，失败时返回 isError: true 和错误信息。

本地文件、data URL、原始 base64 和剪贴板输入必须是 PNG、JPEG、GIF、WebP 或 BMP 格式，单张不超过 20 MiB。HTTP/HTTPS URL 会作为 URL 直接传给 OpenAI-compatible API。

本地运行

npm run dev      # tsx 直接运行，无需构建
# 或
npm run build && npm start

服务通过 stdio 收发 MCP 消息——从 stdin 读 JSON-RPC，向 stdout 写回响应。

项目结构

clipboard-vision-mcp/
├── package.json
├── tsconfig.json
├── .env.example
└── src/
    ├── index.ts              # MCP server 入口，注册工具和 stdio transport
    ├── config.ts             # 加载和校验 env 配置
    ├── tools/
    │   └── recognize.ts      # 视觉工具定义和 handler
    ├── providers/
    │   └── openai.ts         # OpenAI-compatible 视觉调用
    └── inputs/
        ├── index.ts          # resolveImage() 分发器
        ├── types.ts
        ├── image.ts          # 图片 MIME、大小、magic-byte 校验
        ├── file.ts           # 本地路径转 base64
        ├── url.ts            # HTTP(S) URL 透传
        ├── base64.ts         # base64 / data URL
        └── clipboard.ts      # macOS / Windows / Linux 剪贴板图片读取

License

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

clipboard-vision-mcp

快速开始

1. 准备运行环境

2. 准备剪贴板工具

3. 配置 MCP Host

4. 验证

功能

配置项

工具说明

recognize_image

本地运行

项目结构

License

`recognize_image`