mcp-vision-server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-vision-server Describe the image at /home/user/photos/cat.jpg"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-vision-server
A lightweight MCP server exposing a single tool — describe_image — that forwards a local image file to any OpenAI-compatible vision endpoint and returns the text description.
Most LLMs can't see an image you drop into a chat. This server bridges that gap: the host AI calls describe_image with a file path, your vision model does the actual seeing, and the description flows back into the conversation.
┌──────────┐ MCP (stdio) ┌─────────────────┐ HTTP POST ┌──────────────────┐
│ Client │ ─── describe_image ─▶│ mcp-vision-srv │ ── image+prompt ──▶│ Vision Endpoint │
│ (AI) │ ◀── text description │ (this repo) │ ◀──── JSON resp ───│ (vLLM/Ollama/…) │
└──────────┘ └─────────────────┘ └──────────────────┘The server speaks MCP over stdio — it doesn't serve HTTP itself. It reads the file from disk, base64-encodes it, POSTs to your endpoint, and hands the response back as tool output.
Requirements
Python ≥ 3.10
uvinstalledA running vision endpoint that speaks the OpenAI chat-completions schema
That last one is not optional. This server has no model of its own — without something listening at VISION_ENDPOINT, every call fails. See Supported Endpoints.
Related MCP server: z_ai_vision_mcp_server_clone
Install
No clone needed — uvx can run it straight from the repo:
uvx --from git+https://github.com/joshsssn/mcp-vision-server mcp-vision-serverYour MCP client will run this for you once configured; the command above is mainly useful to check the server starts.
Claude Code, one line:
claude mcp add vision \
--env VISION_ENDPOINT=http://localhost:11434/v1/chat/completions \
--env VISION_MODEL=llama3.2-vision \
-- uvx --from git+https://github.com/joshsssn/mcp-vision-server mcp-vision-serverVS Code (Copilot Chat) — add to .vscode/mcp.json in your workspace, or to your user settings:
{
"servers": {
"mcp-vision-server": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"git+https://github.com/joshsssn/mcp-vision-server",
"mcp-vision-server"
],
"env": {
"VISION_ENDPOINT": "https://api.openai.com/v1/chat/completions",
"VISION_API_KEY": "sk-your-key-here",
"VISION_MODEL": "gpt-4o"
}
}
}
}Claude Desktop — add to claude_desktop_config.json:
{
"mcpServers": {
"mcp-vision-server": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/joshsssn/mcp-vision-server",
"mcp-vision-server"
],
"env": {
"VISION_ENDPOINT": "https://api.openai.com/v1/chat/completions",
"VISION_API_KEY": "sk-your-key-here",
"VISION_MODEL": "gpt-4o"
}
}
}
}Working from a local clone instead? Replace the
git+https://…argument with the path to the repo root.
Local development
git clone https://github.com/joshsssn/mcp-vision-server.git
cd mcp-vision-server
cp .env.example .env # edit with your endpoint URL, API key, and model name
uvx --from . mcp-vision-serverConfiguration
All settings come from environment variables, or a .env file in the project root:
Variable | Default | Description |
|
| OpenAI-compatible vision API URL |
|
| Bearer token for the endpoint |
|
| Model name the endpoint expects |
|
| Request timeout in seconds |
|
| Reject images larger than this |
The defaults target a local Ollama install, so ollama run llama3.2-vision plus a zero-config client entry is enough to get going.
The env block in your client config overrides .env. Use .env for local dev, the client block for anything you share — no keys end up in the repo either way.
See .env.example for a ready-to-copy template.
Tool: describe_image
Parameter | Type | Required | Default |
|
| yes | — |
|
| no |
|
image must be an absolute path to a file on disk — not a URL, not a pasted image. Supported formats: PNG, JPG, JPEG, GIF, WEBP.
C:\Users\photos\cat.jpg
/home/user/images/screenshot.pngprompt is any natural-language instruction for the vision model:
"Describe this image in detail.""Extract all text from this image.""What colors dominate this image?""Is there a person in this image? If so, describe them."
Example call:
{
"tool": "describe_image",
"arguments": {
"image": "/home/user/photos/sunset.jpg",
"prompt": "What colors dominate this image? Is there a person in it?"
}
}Supported Endpoints
Anything implementing the OpenAI chat-completions schema with image_url content parts:
Endpoint | Example URL | Notes |
| Easiest local setup | |
| GUI-friendly | |
| Great for self-hosted | |
| Cloud, requires API key | |
Custom / self-hosted |
| Anything OpenAI-compatible |
Troubleshooting
invalid peer certificate: UnknownIssuer on startup. uv uses its own certificate store and doesn't know about TLS-inspecting antivirus software or corporate proxies. Add "UV_NATIVE_TLS": "1" to the env block to make it use the system store instead.
Connection refused / timeout on every call. Nothing is listening at VISION_ENDPOINT. Confirm the endpoint independently before blaming the server:
curl $VISION_ENDPOINT -H "Content-Type: application/json" \
-d '{"model":"llama3.2-vision","messages":[{"role":"user","content":"hi"}]}'Tool doesn't appear in the client. Check the MCP logs — in VS Code, the Output panel has a channel per server. A failure to install the package shows up as a non-zero exit before initialize ever completes.
Image rejected for size. Raise VISION_MAX_IMAGE_BYTES, or downscale first. Base64 encoding inflates the payload by roughly a third, so the limit is deliberately conservative.
Project Structure
mcp-vision-server/
├── pyproject.toml
├── .env.example
├── .gitignore
├── README.md
├── LICENCE
└── src/
└── mcp_vision_server/
├── __init__.py
└── server.pyLicense
MIT — do whatever.
Available Tools
1 tooldescribe_imageA
Pass a local image file to a vision-capable AI and get back a text description.
IMPORTANT: The image parameter MUST be a local absolute file path on disk.
Do NOT pass URLs, base64 strings, or data URIs — always provide the full
absolute path to an image file (e.g. "C:\Users\photos\cat.jpg" or
"/home/user/images/pic.png"). Supported formats: PNG, JPG, JPEG, GIF, WEBP.
Parameters: image (str, required): Local absolute file path to the image. prompt (str, optional): Instruction for the vision model. Defaults to 'Describe this image in detail.'
Returns: Text description produced by the vision model.
Inputs: image (required), prompt.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 1 tool
With only one tool, there is no possibility of confusion or overlap. The tool's purpose is uniquely defined.
The single tool follows a clear verb_noun pattern (describe_image), which is consistent and descriptive.
A single tool is on the thin side, but reasonable for a narrowly scoped vision-description server. It feels minimal but not trivial.
The tool fully covers the server's stated purpose of describing images from local files, with no obvious missing operations for that domain.
Maintenance
Related MCP Connectors
MCP server exposing the YourImageShare upload API (upload/list/delete) as tools for AI agents.
Focused MCP server for OpenAI image/audio generation (v2.0.0). Wraps endpoints via HAPI CLI.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
MCP server for Qwen Image 3 AI image generation
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn 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.396 npm10MIT
- FlicenseBqualityDmaintenanceOpenAI-compatible MCP server for running image analysis tools against your own vision model endpoint.717 npm-
- AlicenseAqualityDmaintenanceMCP server that provides an analyze_image tool using OpenAI-compatible vision LLMs to describe images from file paths, URLs, or base64 data.115 npm1MIT
- AlicenseAqualityDmaintenanceMCP server that exposes an analyze_image tool using Gemini vision models to describe or analyze images from local paths, URLs, or base64 data URIs.112 npmMIT