mcp-vision

An MCP server that describes local images using a configurable vision model.

It is designed for text-only models in VS Code Copilot Chat. The model calls describe_image only when it needs to understand an image, so it does not send a vision request on every chat turn.

Providers

The server works with any OpenAI-compatible vision API. It sends POST /chat/completions requests with the image as a base64 data URL. It is not tied to one provider.

Some providers you can use:

| Provider | Base URL | Example model | | --- | --- | --- | | OpenCode Go | https://opencode.ai/zen/go/v1 | qwen3.7-plus | | OpenAI | https://api.openai.com/v1 | gpt-4o-mini | | Ollama (local) | http://localhost:11434/v1 | llava | | LM Studio (local) | http://localhost:1234/v1 | any loaded model |

OpenCode Go is used below as one example. Any provider in the table works the same way.

Requirements

• Node.js 20 or newer
• pnpm
• An API key for your chosen provider

Configuration

Required environment variables:

• VISION_API_KEY - API key for your vision provider
• VISION_BASE_URL - Base URL of an OpenAI-compatible API endpoint
• VISION_MODEL - Name of the vision model to use

Optional environment variables:

• VISION_MAX_TOKENS - default: 2048
• VISION_THINKING - default: false. Only set to true for providers that support the thinking parameter.
• VISION_MAX_IMAGE_BYTES - default: 8388608
• VISION_TIMEOUT_MS - default: 120000
• VISION_CACHE - default: true
• VISION_CACHE_SIZE - default: 100

Supported image types are PNG, JPG, JPEG, WebP, GIF, and BMP.

Example: OpenCode Go

Set these values for the OpenCode Go provider:

• VISION_API_KEY - your OpenCode Go API key
• VISION_BASE_URL - https://opencode.ai/zen/go/v1
• VISION_MODEL - qwen3.7-plus

Build and run from source

From the repository root:

pnpm install
pnpm --filter mcp-vision build

The server entry point is apps/mcp-vision/dist/index.js.

VS Code configuration

Open the user MCP configuration with MCP: Open User Configuration and add a server entry. Use an input variable for the API key instead of saving it in the file. The command runs the published package with npx, so npm downloads it on first use and there is no need to install it globally.

Example entry for the OpenCode Go provider:

{
  "mcp-vision": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@chauthan/mcp-vision"],
    "env": {
      "VISION_API_KEY": "${input:visionApiKey}",
      "VISION_BASE_URL": "https://opencode.ai/zen/go/v1",
      "VISION_MODEL": "qwen3.7-plus"
    }
  }
}

After saving the file:

1. Run MCP: List Servers.
2. Start or restart the mcp-vision server.
3. Confirm that describe_image is visible in Chat tools.

Example prompt

Ask a text-only model to use the tool with an image path, for example: Describe the image at C:\images\screen.png and tell me what is wrong.

The image path must be available to the MCP process. Absolute paths are recommended.

Security

The server can read any image path passed to it. Only use it with trusted models and workspaces. Keep the API key in VS Code secret input storage or an environment variable.