Vision Relay

MCP Vision Relay wraps local Gemini/Qwen multimodal CLIs into a unified MCP tool so text-only models can instantly gain vision skills.

typescript

3

GitHub Stars

typescript

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ah-wq-mcp-vision-relay": {
      "command": "npx",
      "args": [
        "tsx",
        "/absolute/path/to/mcp-vision-relay/src/index.ts"
      ]
    }
  }
}

MCP Vision Relay encapsulates locally installed multimodal CLIs (currently Gemini CLI and Qwen CLI) as an MCP server so tools like Claude and Codex with MCP support can access image understanding capabilities without changing providers. It handles input validation, can run CLIs in sandbox, and returns structured outputs with metadata for easy UI presentation.

How to use

You register the Vision Relay as an MCP server in your MCP client, then call its tools from your conversations or tasks. The server exposes two multimodal tools that connect to Gemini CLI and Qwen CLI to analyze images from local paths, URLs, or base64 data. Use the tools through a compatible MCP client by selecting mcp-vision-relay in your tool list and invoking the analyze commands as you would any other MCP tool.

How to install

Prerequisites you need to meet before install:

Node.js 18 or later
Gemini CLI installed and reachable from your shell
Qwen CLI installed and reachable from your shell
Authentication for the Gemini/Qwen CLIs so commands like gemini -p "hi" and qwen -p "hi" return results

Install & start the MCP Vision Relay server

npm install
npm run build
npm run dev

# Production start
npm run start

Register the MCP server with your MCP client

Choose one of the supported registration commands below to attach Vision Relay to your MCP session. Do not run the development start command inside the registration command, as it may print extra text on stdout that interferes with the MCP handshake.

claude mcp add mcp-vision-relay -- npx tsx /absolute/path/to/mcp-vision-relay/src/index.ts

codex mcp add mcp-vision-relay -- node /absolute/path/to/mcp-vision-relay/dist/index.js

Configuration and inputs

The Vision Relay supports configurable execution options and will validate inputs automatically. For each tool you can specify a prompt, model, output format, sandbox mode, extra flags, and a timeout. It handles local files, HTTP(S) URLs, and base64 inputs, and will create temporary files as needed, cleaning up after use.

Troubleshooting and notes

If you encounter handshake issues during MCP registration, ensure you run the registration command in a stable shell session and avoid wrapping the registration command with other processes that might produce extraneous stdout. If image processing fails, verify the CLI tools are installed and accessible, and validate that the image input meets the allowed size and extension constraints.

Project structure overview

The project exposes a modular structure to support multiple CLI providers and a clean MCP server surface. Core areas include: CLI provider adapters, MCP server wiring, tools registration, and common utilities for file handling and CLI scheduling.

Available tools

gemini_analyze_image

Analyzes an image using the Gemini CLI and returns a descriptive result, supporting input via local path, URL, or base64 and optional prompts, model overrides, and output formats.

qwen_analyze_image

Analyzes an image using the Qwen CLI with similar input support as Gemini, automatically converting local files to data URLs when needed and returning structured outputs.