Visual MCP
lilexuan/visual-mcp
Análise de imagens locais para modelos texto-only via MCP
Ver no GitHubServidor MCP local que adiciona compreensão de imagens a modelos apenas-texto através de provedores de visão configuráveis. Suporta análise de arquivos PNG, JPEG, WebP e GIF, com suporte a OpenAI, APIs compatíveis e Anthropic.
Instalação
npx convez-ai lilexuan/visual-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Adicionar visão computacional a assistentes IA baseados em texto
- Processar e analisar imagens locais com modelos de visão cloud
- OCR e extração de conteúdo visual em pipelines de automação
Veredito

Solução pragmática para estender modelos texto com visão via MCP. Bem estruturada, suporta múltiplos provedores e configuração simples por variáveis de ambiente, ideal para quem precisa processar imagens locais em fluxos de Claude.
README
A tradução para o português deste README ainda está na fila.
visual-mcp
English | 简体中文
visual-mcp is a local stdio MCP server that lets text-only clients analyze explicitly provided local image paths through one configured vision model provider.
It supports PNG, JPEG, WebP, and non-animated GIF images. It does not read private client caches, clipboard images, PDFs, videos, webpages, screenshots, or any other implicit visual source.
Features
- Local
stdioMCP server for explicit local image analysis. - One provider configured entirely through environment variables.
- Provider adapters for OpenAI Chat Completions-compatible APIs, OpenAI Responses API, and Anthropic Messages API.
- Per-request overrides for model, detail level, and output language.
- Structured tool output with readable text, observations, OCR text, warnings, and provider metadata.
Install
If the package is available from npm:
npm install -g visual-mcp
If you are installing from a local package file:
npm install -g .\visual-mcp-1.0.1.tgz
Claude Code can then start the server with:
{
"mcpServers": {
"visual-mcp": {
"command": "visual-mcp"
}
}
}
opencode can configure the server under the mcp field:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"visual-mcp": {
"type": "local",
"command": ["visual-mcp"],
"enabled": true
}
}
}
You can also run a local .tgz package through npx without global installation:
{
"mcpServers": {
"visual-mcp": {
"command": "npx",
"args": ["-y", "C:\\path\\to\\visual-mcp-1.0.1.tgz"]
}
}
}
For opencode:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"visual-mcp": {
"type": "local",
"command": ["npx", "-y", "C:\\path\\to\\visual-mcp-1.0.1.tgz"],
"enabled": true
}
}
}
Configuration
visual-mcp is configured with environment variables. There is no provider config file and only one provider is active at a time.
Required variables:
| Variable | Description | Example |
|---|---|---|
VISUAL_MCP_PROVIDER_TYPE | Provider adapter type. | openai-chat |
VISUAL_MCP_MODEL | Vision model name. | gpt-4.1-mini |
VISUAL_MCP_API_KEY | API key for the configured provider. | sk-... |
Optional variables:
| Variable | Description | Default |
|---|---|---|
VISUAL_MCP_PROVIDER_NAME | Name shown in tool output metadata. | default |
VISUAL_MCP_BASE_URL | Custom API base URL. Useful for OpenAI-compatible gateways. | OpenAI or Anthropic default |
VISUAL_MCP_MAX_TOKENS | Maximum output tokens. | 1200 |
VISUAL_MCP_DETAIL | Vision detail level: low, high, or auto. | auto |
VISUAL_MCP_LANGUAGE | Output language policy. Use auto to follow the question language. | auto |
VISUAL_MCP_MAX_IMAGE_BYTES | Maximum accepted image size in bytes. | 20971520 |
Temporary PowerShell setup:
$env:VISUAL_MCP_PROVIDER_TYPE = "openai-chat"
$env:VISUAL_MCP_MODEL = "gpt-4.1-mini"
$env:VISUAL_MCP_API_KEY = "sk-..."
$env:VISUAL_MCP_BASE_URL = "https://api.openai.com/v1"
Persist user environment variables on Windows:
[Environment]::SetEnvironmentVariable("VISUAL_MCP_PROVIDER_TYPE", "openai-chat", "User")
[Environment]::SetEnvironmentVariable("VISUAL_MCP_MODEL", "gpt-4.1-mini", "User")
[Environment]::SetEnvironmentVariable("VISUAL_MCP_API_KEY", "sk-...", "User")
If you prefer to pass variables from an MCP client config, use the client's environment field. For opencode:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"visual-mcp": {
"type": "local",
"command": ["visual-mcp"],
"enabled": true,
"environment": {
"VISUAL_MCP_PROVIDER_TYPE": "openai-chat",
"VISUAL_MCP_MODEL": "gpt-4.1-mini",
"VISUAL_MCP_API_KEY": "sk-..."
}
}
}
}
Do not commit real API keys. Keep shared setup notes in this README with placeholder values only.
Provider Types
VISUAL_MCP_PROVIDER_TYPE supports:
openai-chat: OpenAI Chat Completions-compatible APIs.openai-responses: OpenAI Responses API.anthropic: Anthropic Messages API.
For an OpenAI-compatible gateway, set a custom base URL:
$env:VISUAL_MCP_PROVIDER_TYPE = "openai-chat"
$env:VISUAL_MCP_MODEL = "your-vision-model"
$env:VISUAL_MCP_API_KEY = "your-api-key"
$env:VISUAL_MCP_BASE_URL = "https://your-gateway.example/v1"
For Anthropic:
$env:VISUAL_MCP_PROVIDER_TYPE = "anthropic"
$env:VISUAL_MCP_MODEL = "claude-sonnet-4-20250514"
$env:VISUAL_MCP_API_KEY = "sk-ant-..."
Tool
analyze_image
Input parameters:
path: required local image path.question: required question or visual task for the vision model.model: optional model override for this call.detail: optional detail level, one oflow,high, orauto.language: optional output language. Defaults to following the question language.
The tool returns readable text and structuredContent:
{
"answer": "...",
"description": "...",
"observations": ["..."],
"ocr_text": "",
"uncertainties": [],
"provider": "default",
"model": "gpt-4.1-mini",
"usage": {},
"warnings": []
}
Example prompt:
Use visual-mcp to analyze this image: C:\path\to\image.png. What UI issues are visible?
All provider adapters send image content as inline base64/data URLs. The server does not log API keys, image bytes, or base64 payloads.
Local Development
npm install
npm test
npm run typecheck
npm run build
The build output is generated in dist/. To run the server directly from a cloned repository:
npm run dev
When testing a local build from an MCP client, point the client to the built CLI:
{
"mcpServers": {
"visual-mcp": {
"command": "node",
"args": ["C:\\path\\to\\visual-mcp\\dist\\cli.js"]
}
}
}
Package Locally
Run the validation commands first:
npm test
npm run typecheck
npm run build
Create a local package:
npm pack
For packaging changes, also check the package contents without creating a committed artifact:
npm pack --dry-run