convez.ai
MCP ServerIntegração & APIsIntermediário
lilexuan

Visual MCP

lilexuan/visual-mcp

Análise de imagens locais para modelos texto-only via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-mcp

1 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

Estrelas
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 5 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

CI License: MIT TypeScript 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 stdio MCP 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:

VariableDescriptionExample
VISUAL_MCP_PROVIDER_TYPEProvider adapter type.openai-chat
VISUAL_MCP_MODELVision model name.gpt-4.1-mini
VISUAL_MCP_API_KEYAPI key for the configured provider.sk-...

Optional variables:

VariableDescriptionDefault
VISUAL_MCP_PROVIDER_NAMEName shown in tool output metadata.default
VISUAL_MCP_BASE_URLCustom API base URL. Useful for OpenAI-compatible gateways.OpenAI or Anthropic default
VISUAL_MCP_MAX_TOKENSMaximum output tokens.1200
VISUAL_MCP_DETAILVision detail level: low, high, or auto.auto
VISUAL_MCP_LANGUAGEOutput language policy. Use auto to follow the question language.auto
VISUAL_MCP_MAX_IMAGE_BYTESMaximum 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 of low, high, or auto.
  • 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
Ver o original no GitHub

Bom para

Relacionados