Skip to main content
Glama
systemmin

image-mcp

by systemmin
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

image-mcp · 视觉识别 MCP 服务器

一个基于 Model Context Protocol 的图片识别服务器，统一封装三大视觉 API 后端，让 Claude Desktop / Cursor / 任何 MCP 客户端都能调用图片描述、问答与多图分析能力。

📦 npm 包名:@systemmin/image-mcp(bin 命令 image-mcp),可直接 npx @systemmin/image-mcp 运行,无需克隆仓库。

✨ 支持的视觉后端

Provider

服务

适用场景

anthropic

Claude (Anthropic) API

用户提到的 "code plan API"，效果最强

zhipu

智谱 API (GLM-4V 等)

国产视觉模型，国内访问稳定

ollama

Ollama (本地 llava / llama3.2-vision)

本地离线运行，零成本、隐私好

所有后端通过统一的 provider 参数在运行时动态切换，无需重启。

Related MCP server: llm-vision-mcp

🧰 暴露的 MCP Tools

Tool

参数

说明

vision_describe

path, provider?

生成单张图片的详细文字描述/识别结果

vision_qa

path, question, provider?

针对图片提问，模型按图片内容回答 (VQA)

vision_analyze

paths[], prompt, provider?

对多张图片综合分析/对比

  • provider 可选；不传时按 DEFAULT_PROVIDER -> anthropic -> zhipu -> ollama 优先级自动选择第一个已配置的后端。

  • 返回结果开头会标注实际使用的 provider，例如 [provider: zhipu]。

📦 安装

方式一:直接用 npx(推荐,无需克隆)

npx @systemmin/image-mcp

或全局安装:

npm install -g @systemmin/image-mcp
image-mcp

方式二:从源码构建

# 需要 Node.js >= 20
git clone https://github.com/systemmin/image-mcp.git
cd image-mcp
npm install
npm run build

⚙️ 配置

复制 .env.example 为 .env 并填入密钥：

cp .env.example .env
# Claude (Anthropic)
ANTHROPIC_API_KEY=sk-ant-xxx
ANTHROPIC_MODEL=claude-sonnet-4-5-20250929

# 智谱
ZHIPU_API_KEY=xxx.xxx
ZHIPU_MODEL=glm-4v

# Ollama (本地)
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_MODEL=llava

# 默认后端
DEFAULT_PROVIDER=anthropic

只需配置你想用的后端的密钥即可，其余可留空。Ollama 无需密钥，但要先 ollama pull llava 拉取视觉模型并保持服务运行。

⏱️ 工具调用超时(重要)

MCP_TOOL_TIMEOUT 是 MCP 客户端(Claude Code / Claude Desktop)侧的环境变量,不是本 server 的配置。视觉 API 处理大图较慢,若不调大超时,客户端往往在工具返回前就超时报错(实测大图极易触发)。

在启动客户端之前设置(单位:毫秒,下例为 5 分钟):

# Windows CMD
set MCP_TOOL_TIMEOUT=300000

# PowerShell
$env:MCP_TOOL_TIMEOUT="300000"

# macOS / Linux
export MCP_TOOL_TIMEOUT=300000

设好后再启动 claude 或 Claude Desktop;也可加入系统环境变量永久生效。

🔌 接入 MCP 客户端

Claude Code(命令行,推荐)

用官方命令一键添加,无需手改 JSON:

# 仅当前项目可用(local scope,默认)
claude mcp add image-mcp -- npx @systemmin/image-mcp

# 或全局所有项目可用(user scope)
claude mcp add image-mcp --scope user -- npx @systemmin/image-mcp

需要传入 API 密钥时用 -e(可多次):

claude mcp add image-mcp --scope user -e ANTHROPIC_API_KEY=sk-ant-xxx -e DEFAULT_PROVIDER=anthropic -- npx @systemmin/image-mcp

也可不传 -e,改为在你运行 claude 的目录放一个 .env 文件(dotenv 会自动加载)。 验证是否注册成功:claude mcp list。

或手动编辑配置文件 ~/.claude.json(Windows: C:\Users\<用户名>\.claude.json,注意文件名带前导点),在顶层 mcpServers 中加入:

{
  "mcpServers": {
    "image-mcp": {
	  "type": "stdio",
      "command": "npx",
      "args": ["@systemmin/image-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxx",
        "DEFAULT_PROVIDER": "anthropic"
      }
    }
  }
}

Claude Desktop

编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json，Windows: %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "image-mcp": {
	  "type": "stdio",
      "command": "npx",
      "args": ["@systemmin/image-mcp"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-xxx",
        "ZHIPU_API_KEY": "xxx.xxx",
        "DEFAULT_PROVIDER": "anthropic"
      }
    }
  }
}

也可不写 env，改为在项目目录放 .env 文件（dotenv 会自动加载）。若从源码运行，把 command/args 换成 "command": "node", "args": ["/path/to/image-mcp/dist/index.js"]。

Cursor / 其他 MCP 客户端

按对应客户端文档添加一个 stdio 类型的 MCP server，命令为 npx @systemmin/image-mcp（全局安装后也可直接用 image-mcp）。

🧪 调试

用官方 Inspector 交互测试：

npm run inspector

会打开网页界面，可手动调用三个工具、查看请求/响应。

🏗️ 项目结构

src/
├── index.ts              # MCP 服务器入口，注册 3 个工具
├── providers/
│   ├── index.ts          # VisionProvider 接口 + getProvider 工厂
│   ├── anthropic.ts      # Claude API 适配器
│   ├── zhipu.ts          # 智谱 API 适配器
│   └── ollama.ts         # Ollama API 适配器
└── utils/
    ├── image.ts          # 图片读取 + base64 编码 + MIME 推断
    └── config.ts         # 环境变量加载 + provider 解析

架构说明

三个工具本质都调用 VisionProvider.analyze(images, prompt)，区别只在 prompt：

  • vision_describe -> 固定描述 prompt

  • vision_qa -> 用户问题作为 prompt

  • vision_analyze -> 多图 + 自定义 prompt

新增一个视觉后端只需实现 VisionProvider 接口并在 getProvider 注册即可。

📜 脚本

命令

作用

npm run build

TypeScript 编译到 dist/

npm start

运行编译后的服务器

npm run inspector

启动 MCP Inspector 调试

Available Tools

3 tools
vision_analyzeB

对多张本地图片进行综合分析/对比，根据自定义 prompt 给出结论

ParametersJSON Schema
NameRequiredDescriptionDefault
pathsYes本地图片文件路径数组（至少一张）
promptYes对这组图片的分析要求或问题
providerNo视觉 API 后端: anthropic | zhipu | ollama。不传则使用默认 provider

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It does not disclose behavioral traits such as whether the tool modifies data, authentication requirements, rate limits, or output format. This is a significant gap for a tool that likely returns conclusions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The single-sentence description is concise and front-loaded with purpose. However, it could benefit from slight restructuring to highlight key aspects.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description covers the main purpose but lacks details on output format and provider selection behavior. Without an output schema, the description should at least indicate what the tool returns.

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 adds no additional semantic information beyond what the schema already provides for parameters paths, prompt, and provider.

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 performs comprehensive analysis or comparison on multiple local images using a custom prompt. This differentiates it from sibling tools vision_describe (likely single image description) and vision_qa (question answering).

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 for analysis/comparison tasks but provides no explicit guidance on when to use this tool versus alternatives. Siblings are listed but not described, missing the opportunity to clarify tool selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vision_describeB

对一张本地图片生成详细的文字描述/识别结果

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes本地图片文件的绝对或相对路径
providerNo视觉 API 后端: anthropic | zhipu | ollama。不传则使用默认 provider

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so the description must disclose behavioral traits. It merely states the function without mentioning side effects, permissions, rate limits, or limitations (e.g., file formats, language, accuracy). This is insufficient for a tool with no safety annotations.

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 a single, efficient sentence conveying the core functionality. No fluff, well front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity (2 parameters, no output schema), the description is adequate but minimal. It does not specify output format, language, or behavior for different providers. More detail would benefit an AI agent's understanding.

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% with descriptions for both parameters. The tool description adds only the qualifier 'local' for the image, which is already implied by the path description. No additional semantic value beyond the schema.

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 it generates detailed text descriptions or recognition results for local images. The verb 'generate' and resource 'local image' are specific, and the tool name combined with sibling names (vision_analyze, vision_qa) helps distinguish its purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus its siblings (vision_analyze, vision_qa). The description does not mention prerequisites, context, or exclusions, leaving the agent without decision criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vision_qaA

针对一张本地图片提问，模型根据图片内容回答

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes本地图片文件的路径
providerNo视觉 API 后端: anthropic | zhipu | ollama。不传则使用默认 provider
questionYes针对图片提出的问题

TDQS

A3.7/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It states the core behavior (answer based on image content) but lacks details on output format, file size limits, supported image types, or whether the operation is read-only. Adequate but not thorough.

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?

Single sentence that is front-loaded with the core action and resource. No wasted words; every part adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and moderate complexity (3 parameters), the description fails to mention what the answer looks like (text, JSON, etc.) or any error handling. It is functional but lacks completeness for a tool with no annotations.

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 baseline of 3 applies. Description does not add extra semantic information beyond what the schema already provides for each parameter; it merely reiterates in a different language.

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?

Description clearly states verb 'ask a question' and resource 'local image', and the action of answering based on content. It effectively distinguishes from sibling tools 'vision_analyze' and 'vision_describe' which imply analysis or description rather than Q&A.

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?

Description implies usage when a user has a specific question about a local image, but provides no explicit guidance on when to use alternatives or when not to use this tool. The context from sibling names is present but not leveraged.

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. Dates show when Glama detected each change.

  1. 3 tool updatesv1.0.0
    • First observedvision_analyze
    • First observedvision_describe
    • First observedvision_qa
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation5/5

Each tool targets a distinct task: multi-image analysis with custom prompt, single-image description, and single-image Q&A. No overlap in functionality.

Naming Consistency5/5

All tools follow consistent 'vision_<verb>' pattern with clear, descriptive verbs (analyze, describe, qa).

Tool Count5/5

Three tools is well-scoped for an image analysis server, covering the essential operations without bloat or insufficiency.

Completeness4/5

The set covers core image analysis tasks (description, QA, multi-image comparison). Missing potential features like image search or generation, but these are beyond the stated domain.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Luma MCP

    JochenYang
    A
    license
    A
    quality
    A
    maintenance
    Multi-model vision understanding MCP server that provides unified image analysis for AI assistants without native vision, supporting models like GLM-4.6V, DeepSeek-OCR, Qwen3-VL-Flash, and more.
    1
    947
    113
    MIT

  • llm-vision-mcp

    ghbalf
    A
    license
    Not graded
    quality
    C
    maintenance
    An MCP server that enables any LLM to describe images from file paths, URLs, or base64 data by forwarding them to a supported vision provider such as OpenAI, Anthropic, or local Ollama models.
    1,060
    10
    MIT

  • vision-mcp

    menoxz
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server for analyzing images using multiple vision LLM providers (OpenCode, OpenAI, Anthropic, Google, and custom OpenAI-compatible endpoints). Provides tools to analyze single or multiple images, list providers, and test vision capabilities.
    MIT

  • llm-vision

    maple-red
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP server that provides a 'borrowed eye' for text-only LLMs, enabling them to identify and describe local images via the Qwen VL vision model, including face recognition, scene description, OCR, and targeted visual questioning.
    1
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/systemmin/image-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server