Skip to main content
Glama
Amengclass

Vision MCP

by Amengclass
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Vision MCP

The Universal Vision-Language Model MCP Server — Image Understanding & OCR for Any MCP Client

Version Downloads License Platform Built with TypeScript PRs Welcome

English | 中文 | 日本語 | Deutsch | Changelog

Vision MCP is a universal MCP server that plugs any OpenAI-compatible vision-language model into any MCP client — Claude Code, Reasonix, Cursor, Windsurf, VS Code and more. It exposes two tools: image understanding (describe & Q&A) and OCR (text extraction). Your images never leave your machine.

It is not tied to any model vendor: point it at local Ollama, vLLM, LM Studio, or any remote OpenAI-compatible endpoint — just change configuration, not code.

✨ Highlights

  • 🧠 Model-agnostic — Works with any vision model exposing an OpenAI-compatible API (qwen2.5vl, llama3.2-vision, minicpm-v, GPT-4o, Gemini…), plus Ollama's native API for keep_alive residency

  • 🔌 Client-agnostic — A single server, usable from any MCP client via stdio

  • 📦 Zero-dependency distribution — Ship a single vision-mcp.exe (Node SEA); recipients need no Node.js, no npm, no Python

  • 🖼️ Multi-image — Pass multiple images in one call natively

  • 🔒 Privacy-first — 100% local inference; images never leave the machine (unless you point it at a remote endpoint)

  • 🧭 Smart path handling — Absolute, relative, and ~ paths; clear Chinese/English error messages

  • ⚙️ Fully configurable — Endpoint, model name, API format, keep-alive and timeout via environment variables

Related MCP server: vision-bridge-mcp

🏗️ Architecture

┌──────────────┐   MCP stdio    ┌────────────────────┐   HTTP   ┌───────────────────────┐
│ Any MCP      │ ─────────────→ │  vision-mcp server │ ──────→ │  Vision backend       │
│ client       │ ←───────────── │  (Node/TS or exe)  │ ←────── │  Ollama | vLLM | ...  │
└──────────────┘   text result  └────────────────────┘          └───────────────────────┘

The server is a thin, stateless bridge: it receives image paths from the MCP client, base64-encodes them, forwards them to the vision backend, and returns the model's text answer.

🛠️ Tools

Tool

Description

Arguments

describe_image

Image understanding / visual Q&A

image_paths (required, multi), question (optional)

ocr_image

Extract all text from images, line-preserved

image_paths (required, multi)

🚀 Quick Start

1. Run a vision backend (e.g. Ollama)

ollama pull qwen2.5vl:3b
ollama serve

Verify: curl http://localhost:11434/api/tags should list your model.

2. Get the server

Option A — Single-file executable (no runtime needed):

Download vision-mcp.exe from the Releases page.

Option B — Run from source:

npm install
npm run build

3. Register in your MCP client

Create/merge .mcp.json in your project root (or ~/.claude/.mcp.json for Claude Code globally):

{
  "mcpServers": {
    "vision-mcp": {
      "command": "/path/to/vision-mcp.exe",
      "args": []
    }
  }
}

Running from source? Use "command": "node", "args": ["/path/to/dist/server.cjs"].

4. Use it

「Use vision-mcp to look at ./screenshot.png and describe it」
「OCR the text in ./doc.jpg」

⚙️ Configuration

All settings are optional environment variables, passed via the env field in .mcp.json:

Variable

Default

Description

VLM_API_MODE

ollama

API format: ollama (native /api/chat, supports keep-alive) | openai (standard /v1/chat/completions, any OpenAI-compatible backend)

VLM_BASE_URL

http://localhost:11434 (ollama mode) / http://localhost:11434/v1 (openai mode)

Backend address. openai mode requires the /v1 suffix

VLM_MODEL

qwen2.5vl:3b

Model name

VLM_KEEP_ALIVE

30m

Model residency (Ollama mode only); 0 = unload after each call, -1 = keep forever

VLM_TIMEOUT_MS

300000

Per-call timeout (covers cold-start model load)

Switching backends (example: vLLM)

{
  "mcpServers": {
    "vision-mcp": {
      "command": "/path/to/vision-mcp.exe",
      "args": [],
      "env": {
        "VLM_API_MODE": "openai",
        "VLM_BASE_URL": "http://192.168.1.10:8000/v1",
        "VLM_MODEL": "Qwen/Qwen2.5-VL-3B-Instruct"
      }
    }
  }
}

That's it — no code changes, no rebuild when switching providers.

📦 Distribution to Others

Build the single-file executable:

npm run build:exe     # outputs dist/vision-mcp.exe (~89 MB)

Recipients only need to:

  1. Have their own vision backend (Ollama + model, or set VLM_BASE_URL to a shared/remote service)

  2. Register the exe in any MCP client — no Node, no Python

❓ FAQ

Because the server intentionally exposes exactly two tools: describe_image (image understanding) and ocr_image (OCR). The executable path shown next to the server is the server program itself, not a third tool.

The model is loaded on first use (a few seconds to tens of seconds). Set VLM_KEEP_ALIVE=30m (default) so the model stays resident — subsequent calls return in under a second.

The config is fine; the vision backend is down. Start it: ollama serve, and verify with curl http://localhost:11434/api/tags.

The SEA-built exe embeds your bundle into a copy of node.exe, which invalidates the original Microsoft signature and can trigger false positives. Alternative: build a native binary with Bun: bun build --compile src/server.ts --outfile dist/vision-mcp.exe.

describe_image/ocr_image require a vision (multimodal) model. A text-only model will not read images.

🧑‍💻 Development

npm install          # install dependencies
npm run build        # esbuild bundle → dist/server.cjs
npm test             # end-to-end test against a real backend (official MCP client over stdio)
npm run build:exe    # package single-file executable (Node SEA)

End-to-end tests connect through the official MCP SDK client and exercise both tools, multi-image input, and error paths.

📁 Project Structure

├── src/
│   └── server.ts              # MCP server source (TypeScript)
├── scripts/
│   ├── test-client.mjs        # End-to-end test (official MCP client)
│   └── build-sea.mjs          # Single-file executable builder
├── package.json               # Build/test/package scripts
└── .mcp.json                  # Example registration config

🤝 Contributing

Issues and pull requests are welcome! For new features, please open an issue to discuss before submitting a PR.

  • Run npm run build to ensure the TypeScript compiles

  • Run npm test to ensure existing behavior is preserved

  • Keep changes focused and documented

📄 License

MIT © Ameng

Available Tools

2 tools
describe_imageA

对一张或多张图片进行视觉理解（识图）：可指定任意问题，如描述内容、识别物体、分析图表、理解截图等

ParametersJSON Schema
NameRequiredDescriptionDefault
questionNo你想问关于图片的问题，默认：请详细描述这张图片的内容
image_pathsYes图片路径列表（绝对路径，或相对 MCP server 工作目录；支持 ~ 开头），可传多张

TDQS

A4.2/5.0
Behavior4/5

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

With no annotations provided, the description carries the full burden. It transparently states that the tool can perform visual understanding and answer arbitrary questions, and it supports one or more images. It does not hide side effects because there appear to be none; however, it does not detail limitations like image format support or potential model errors, though these are not critical.

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, front-loaded sentence that efficiently states the tool's purpose and provides relevant examples without unnecessary filler. Every phrase contributes value.

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

Completeness4/5

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

The tool is relatively simple, and the description covers the core purpose, examples, and flexibility of questions. The schema provides complete parameter details, so the description need not explain them again. A minor gap is the lack of explicit differentiation from the sibling tool, but the description is still sufficiently complete for an agent to use it correctly.

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?

The schema already documents both parameters (image_paths and question) with clear descriptions, achieving 100% coverage. The description adds minimal extra meaning beyond the schema, only emphasizing that the question can be arbitrary. Therefore, a baseline of 3 is appropriate.

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 visual understanding on images and allows arbitrary questions, with concrete examples like describing content, recognizing objects, analyzing charts, and understanding screenshots. This distinguishes it from the sibling tool ocr_image, which is likely text-focused.

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

Usage Guidelines4/5

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

The description gives clear context for when to use the tool—any visual understanding task with arbitrary questions—and lists several use cases. It does not explicitly name alternatives or exclusions relative to ocr_image, but the examples imply broad applicability beyond simple OCR.

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

ocr_imageA

提取一张或多张图片中的所有文字（OCR），按原始排版分行输出

ParametersJSON Schema
NameRequiredDescriptionDefault
image_pathsYes图片路径列表（绝对路径，或相对 MCP server 工作目录；支持 ~ 开头），可传多张

TDQS

A4/5.0
Behavior3/5

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

With no annotations, the description carries the full burden. It discloses behavioral traits like supporting one or more images and outputting line-by-line according to original layout, which adds useful context. However, it does not mention edge cases like image quality requirements, error handling, or language support. This is adequate but not rich.

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 concise sentence that packs all essential information: purpose, input type, and output behavior. No wasted words, front-loaded with the core function.

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

Completeness4/5

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

For a simple one-parameter tool with no output schema, the description adequately covers purpose, input, and output format. It could mention possible limitations or error conditions, but the provided detail is sufficient for typical usage. No output schema means the description's mention of line-by-line output is valuable.

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?

There is only one parameter (image_paths) and its schema description already covers path formats (absolute, relative, ~). The description adds no additional parameter-specific semantics, but the schema does the heavy lifting. Baseline 3 is appropriate.

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 function: extract all text from one or more images via OCR, and output it line-by-line preserving original layout. The verb 'extract' and resource 'images' are specific, and the output format detail distinguishes it from the sibling tool 'describe_image', which focuses on visual description rather than text extraction.

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

Usage Guidelines4/5

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

The description implies usage context: use this tool when you need OCR text from images. However, it does not explicitly mention when to prefer describe_image or exclude non-OCR scenarios, leaving some ambiguity. The distinct purpose helps, but no explicit alternatives are named.

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. 2 tool updatesv1.1.0
    • First observeddescribe_image
    • First observedocr_image
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0
Disambiguation4/5

The two tools have clear but slightly overlapping purposes: describe_image offers general visual understanding, while ocr_image specifically extracts text. An agent could theoretically use describe_image for text extraction, but the OCR tool is more direct and precise for that task.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (describe_image, ocr_image), making the tool names predictable and easy to select.

Tool Count3/5

With only 2 tools, the server feels minimal, but it covers the essential tasks of visual understanding and OCR. It's borderline but not unreasonable for a purpose-built vision server.

Completeness4/5

The two tools cover the core needs of image understanding and text extraction, and describe_image is versatile enough to handle many query types. Minor gaps exist, such as no dedicated tools for image comparison or object detection, but these can be handled through describe_image.

Maintenance

ActivityMaintained
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

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/Amengclass/vision-mcp'

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