Visual Enhancement Mcp

mcp-vision-server

[English](README.md) | [简体中文](README.zh-CN.md)

mcp-vision-server is an MCP stdio server that lets MCP clients analyze images and run OCR through an existing OpenAI-compatible vision Chat Completions API.

This document focuses on how to configure and use the server from an MCP client.

What it provides

• vision_analyze: general image understanding with a custom prompt.
• vision_ocr: OCR extraction with optional language and output-format hints.
• Image input through exactly one of:
• imagePath: a local absolute image path available to the MCP server process.
• imageUrl: http://, https://, data:, or file:// URL.
• imageBase64 + imageMediaType: uploaded attachment bytes forwarded by the client.
• OpenAI-compatible upstream request shape: Chat Completions with text plus image_url content.
• Structured MCP output in addition to plain text content.

Required configuration

The server needs an upstream vision model endpoint. At minimum configure:

| Setting | Required | CLI option | Environment variable | Description | Example | | --- | --- | --- | --- | --- | --- | | API base URL | Yes | --api-base-url | VISION_API_BASE_URL | Root URL of the upstream OpenAI-compatible API. Prefer scheme + host only; keep the request path in api-path. | https://api.openai.com | | Model | Yes | --model | VISION_MODEL | Default vision-capable model exposed by the upstream API. A tool call can override it with model. | gpt-4o-mini | | API key | Usually | --api-key | VISION_API_KEY | Bearer token sent as Authorization: Bearer . Omit only when your endpoint does not require authentication. | sk-xxxx |

The final upstream URL is built from:

Example:

VISION_API_BASE_URL=https://api.openai.com
VISION_API_PATH=/v1/chat/completions
=> https://api.openai.com/v1/chat/completions

Full configuration reference

Configuration priority:

CLI arguments > environment variables > defaults

| Purpose | CLI option | Alias | Environment variable | Default | Notes | | --- | --- | --- | --- | --- | --- | | Upstream API base URL | --api-base-url | --vision-api-base-url | VISION_API_BASE_URL | none | Required. Use the API root such as https://api.openai.com. | | Upstream API path | --api-path | --vision-api-path | VISION_API_PATH | /v1/chat/completions | Chat Completions endpoint path. | | Upstream API key | --api-key | --vision-api-key | VISION_API_KEY | none | Added as a Bearer token when set. | | Default model | --model | --vision-model | VISION_MODEL | none | Required. Must support image input. | | Request timeout | --timeout-ms | --vision-timeout-ms | VISION_TIMEOUT_MS | 60000 | Invalid or non-positive environment values fall back to default. | | Default output token limit | --max-tokens | --vision-max-tokens | VISION_MAX_TOKENS | 4096 | Sent upstream as max_tokens when a tool call omits maxTokens. | | MCP server name | --server-name | --mcp-server-name | MCP_SERVER_NAME | mcp-vision-server | Metadata shown to the MCP client. | | MCP server version | --server-version | --mcp-server-version | MCP_SERVER_VERSION | 0.1.4 | Metadata shown to the MCP client. |

Environment-style configuration example:

VISION_API_BASE_URL=https://api.openai.com
VISION_API_PATH=/v1/chat/completions
VISION_API_KEY=sk-xxxx
VISION_MODEL=gpt-4o-mini
VISION_TIMEOUT_MS=60000
VISION_MAX_TOKENS=4096
MCP_SERVER_NAME=mcp-vision-server
MCP_SERVER_VERSION=0.1.4

MCP client configuration

Most MCP clients should register this server as a stdio command. Replace the URL, key, and model with your provider values.

JSON config

Use this shape for clients that accept mcpServers JSON, such as Claude Desktop, Cursor, VS Code-compatible MCP configs, and similar clients:

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-vision-server",
        "--api-base-url", "https://your-api.example.com",
        "--api-path", "/v1/chat/completions",
        "--api-key", "sk-xxxx",
        "--model", "your-vision-model",
        "--timeout-ms", "60000",
        "--max-tokens", "4096"
      ]
    }
  }
}

If your client supports an env block, you can keep secrets out of args:

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "mcp-vision-server"],
      "env": {
        "VISION_API_BASE_URL": "https://your-api.example.com",
        "VISION_API_PATH": "/v1/chat/completions",
        "VISION_API_KEY": "sk-xxxx",
        "VISION_MODEL": "your-vision-model",
        "VISION_TIMEOUT_MS": "60000",
        "VISION_MAX_TOKENS": "4096"
      }
    }
  }
}

Codex

codex mcp add vision -- `
  npx -y mcp-vision-server `
  --api-base-url https://your-api.example.com `
  --api-path /v1/chat/completions `
  --api-key sk-xxxx `
  --model your-vision-model `
  --timeout-ms 60000 `
  --max-tokens 4096

Claude Code

claude mcp add vision -- `
  npx -y mcp-vision-server `
  --api-base-url https://your-api.example.com `
  --api-path /v1/chat/completions `
  --api-key sk-xxxx `
  --model your-vision-model `
  --timeout-ms 60000 `
  --max-tokens 4096

Upstream API contract

The server sends a POST request to the configured Chat Completions URL:

{
  "model": "your-vision-model",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Describe this image." },
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/png;base64,...",
            "detail": "auto"
          }
        }
      ]
    }
  ]
}

Response parsing supports:

• choices[0].message.content as a string.
• choices[0].message.content as an array of text parts.
• choices[0].message.reasoning or reasoning_content as fallback text for compatible providers.

Image source behavior

Exactly one image source must be supplied per tool call.

| Field | Use when | Handling | | --- | --- | --- | | imagePath | The MCP server process can read an absolute local file path. | The file is read, MIME type is inferred from extension, and the image is sent upstream as a data: URL. | | imageUrl | The image is already addressable as http(s)://, data:, or file://. | file:// is read like imagePath; remote URLs are passed upstream as URLs. | | imageBase64 + imageMediaType | The MCP client can pass uploaded attachment bytes directly. | The payload is wrapped as data:;base64,. |

Supported local file extensions for MIME inference: .png, .jpg, .jpeg, .webp, .gif, .bmp.

Drag-and-drop support depends on the host MCP client. If the client does not forward attachment data as imagePath, imageUrl, or imageBase64, the server cannot access that image.

Tools

vision_analyze

Use this tool for general image understanding.

Required:

• prompt: instruction passed to the vision model.
• Exactly one of imagePath, imageUrl, or imageBase64.

Required with imageBase64:

• imageMediaType: for example image/png or image/jpeg.

Optional:

• model: override the configured default model for this call.
• detail: auto, low, or high; forwarded to providers that support image detail.
• maxTokens: positive integer up to 32768; overrides the configured default for this call.

Example:

{
  "name": "vision_analyze",
  "arguments": {
    "imageUrl": "https://example.com/cat.png",
    "prompt": "Describe the main subject and extract any visible text.",
    "detail": "high",
    "maxTokens": 2048
  }
}

vision_ocr

Use this tool for text extraction.

Required:

• Exactly one of imagePath, imageUrl, or imageBase64.

Required with imageBase64:

• imageMediaType.

Optional:

• languageHint: language hint such as en, zh-CN, or ja.
• outputFormat: plain, markdown, or json; default is plain.
• model: override the configured default model for this call.
• detail: auto, low, or high.
• maxTokens: positive integer up to 32768.

Example:

{
  "name": "vision_ocr",
  "arguments": {
    "imageBase64": "",
    "imageMediaType": "image/png",
    "languageHint": "en",
    "outputFormat": "markdown"
  }
}

Tool output

Both tools return plain text in MCP content and structured data in structuredContent:

{
  "text": "recognized or analyzed text",
  "model": "model-used",
  "sourceLabel": "resolved image source",
  "mediaType": "image/png"
}

Provider notes

• The upstream API must accept OpenAI-compatible Chat Completions image input.
• Some providers ignore detail or max_tokens; behavior then follows the provider.
• Large images may increase latency, token usage, and provider-side request size.
• Only one image is accepted per tool call.

Links

• Linux Do

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: goehou
• Source: goehou/Visual-Enhancement-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.