Skip to main content
Glama
llt22

image-recognition-mcp

by llt22
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

clipboard-vision-mcp

npm LINUX DO

中文 | English

给你的编码助手或 AI 工具装上"眼睛"。注册这个 MCP 服务后，原本没有视觉能力的 LLM 可以读取剪贴板截图、本地图片、HTTP(S) 图片 URL、data URL 或 base64 图片，并返回文字描述或对图片问题的回答。

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

使用

1. 准备依赖

需要：

  • Node.js 20 或更高版本

  • 能访问视觉模型的 OpenAI-compatible API key

  • 剪贴板图片读取工具：

    • macOS：brew install pngpaste

    • Windows：系统内置 PowerShell，无需额外安装

    • Linux Wayland：wl-paste（来自 wl-clipboard）

    • Linux X11：xclip

包地址：clipboard-vision-mcp on npm

2. 配置 MCP Host

在 MCP Host 的 mcpServers 中添加，并按你的 OpenAI-compatible provider 填写 env：

{
  "mcpServers": {
    "clipboard-vision": {
      "command": "npx",
      "args": ["-y", "clipboard-vision-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-api-key",
        "OPENAI_MODEL": "your-vision-model",
        "OPENAI_BASE_URL": "https://your-openai-compatible-endpoint/v1"
      }
    }
  }
}

3. 验证

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

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

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

Related MCP server: image_mcp

工具

recognize_image

单个通用图片识别工具。默认读取剪贴板，也可以通过 image 参数传入本地路径、HTTP(S) URL、data URL、base64 或 "clipboard"。

参数

类型

必填

默认值

说明

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 数

示例问题：

  • 描述这张截图

  • 提取图片里的文字

  • 这张 UI 截图里有什么错误提示？

  • 这个图表表达了什么？

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

配置项

除在 MCP Host 的 env 中直接设置外，也支持项目根目录的 .env 文件。MCP Host 传入的环境变量优先级更高。

环境变量

默认值

说明

OPENAI_API_KEY

必填

OpenAI-compatible API key

OPENAI_MODEL

gpt-4o-mini

视觉模型名

OPENAI_BASE_URL

OpenAI 默认地址

OpenAI-compatible 网关地址

OPENAI_TIMEOUT_MS

60000

请求超时时间（毫秒）

LOCAL_FILE_INPUT_ENABLED

true

设为 false 可禁用本地文件路径输入

LOCAL_FILE_ALLOWED_ROOTS

空

路径 allowlist，逗号分隔，例如 /tmp,~/Pictures；空表示允许所有路径

Provider 配置示例：

OPENAI_API_KEY=...
OPENAI_MODEL=your-vision-model
OPENAI_BASE_URL=https://your-openai-compatible-endpoint/v1

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

开发

从源码运行：

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

本地调试：

npm run dev
# 或
npm run build && npm start

如果从本地 clone 作为 MCP server 使用，配置里改用 "command": "node"，args 指向 dist/index.js 的绝对路径。

服务通过 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

Available Tools

1 tool
recognize_imageB

Recognize and analyze an image using the configured vision model. If no image is provided, reads the current clipboard image. Also supports local file paths, http(s) URLs, base64, data URLs, and the literal "clipboard".

ParametersJSON Schema
NameRequiredDescriptionDefault
imageNoImage to recognize. Accepts: http(s) URL, local file path, data: URL, raw base64 string, or the literal "clipboard". Defaults to "clipboard".clipboard
detailNoVision detail level. 'low' is cheaper and faster; 'high' for fine text.auto
promptNoQuestion or instruction about the image, e.g. 'What text is on this sign?'Describe this image in detail, including any visible text.
maxTokensNoMax tokens for the response. Defaults to 1024.

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 must disclose all behavioral traits. It mentions reading clipboard if no image is provided and supported input types, but does not describe potential side effects, read-only status, model limitations, or cost implications. The description is insufficient for full behavioral transparency.

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?

The description is extremely concise with two sentences. The first sentence front-loads the core purpose, and the second adds essential context on input sources. Every sentence contributes value with 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 having no output schema, the description fails to explain what the tool returns after analysis (e.g., text description). It also does not cover potential limitations, authentication, or rate limits. The description is incomplete for a tool with 4 parameters and no output schema.

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 coverage is 100%, so the baseline is 3. The description reinforces the default clipboard behavior and supported formats already covered in the schema, but adds no new semantic meaning beyond what the schema provides. Thus, it meets the baseline without exceeding it.

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 the tool's purpose: recognizing and analyzing images using a vision model, with specific details about input sources. It is a specific verb+resource combination that leaves no ambiguity about the tool's function.

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 by explaining default clipboard behavior and supported formats, but lacks explicit guidance on when to use this tool versus alternatives (none provided) or when not to use it. It provides basic usage context but no exclusions.

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. 1 tool updatev0.2.0
    • First observedrecognize_image
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no ambiguity; the agent will always select the correct tool.

Naming Consistency5/5

A single tool name is trivially consistent with itself, as there is no other tool to conflict.

Tool Count3/5

One tool for image recognition is thin but acceptable if the tool is versatile. The tool handles many input formats, but more specialized tools might be expected.

Completeness4/5

The tool covers image recognition well with multiple input methods, but lacks additional operations like model selection or detailed output control.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers