MCP Vision Relay

🚀 MCP Vision Relay

MCP Vision Relay encapsulates locally installed multimodal CLIs (currently supporting Google Gemini CLI and Qwen CLI) into a Model Context Protocol (MCP) server. It enables MCP - supported tools like Claude and Codex to directly utilize their image - viewing capabilities.

English | Chinese

⚠️ Important Note

When Claude Code connects to providers such as k2, DeepSeek, or MiniMax M2, the current backing models are text - only, with no built - in vision. By relaying calls through Gemini/Qwen CLI, MCP Vision Relay provides an inexpensive way for those deployments to regain multimodal features without switching providers.

✨ Features

• Unified image tools – The gemini_analyze_image and qwen_analyze_image tools support three types of input: paths, URLs, and base64 strings.
• Provider relay architecture – Switch or extend different CLIs through the provider abstraction, while retaining the ability to configure models, output formats, etc.
• Robust input handling – Automatically verify image size and extension. Download or write to temporary files when necessary and clean them up after use.
• Configurable execution – Support optional sandbox, timeout, additional flags, model override, and configuration via .env/environment variables.
• Actionable outputs – Regularize stdout and attach metadata for easy display in the UI or subsequent processing by the client.

🚀 Quick Start

Prerequisites

1. Node.js ≥ 18
2. Gemini CLI and/or Qwen CLI installed and directly callable from the command line.
3. Login/authentication for the corresponding CLI is completed (ensure that gemini -p "hi" and qwen -p "hi" can return results).

Install & Build

npm install
npm run build

Run the MCP server

# Development mode (start TypeScript directly with tsx)
npm run dev

# Production mode (use compiled artifacts)
npm run start

The MCP server communicates with the MCP client via stdio, suitable for commands like claude mcp add and codex mcp add.

💻 Usage Examples

Claude

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

Codex CLI

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

After completion, you can select the mcp-vision-relay tool for invocation in the session/task.

📚 Documentation

Available Tools

gemini_analyze_image

Analyze an image and return the description provided by the Gemini CLI.

The returned content includes a Markdown text and metadata (model, input source, elapsed time, etc.).

qwen_analyze_image

Perform image understanding using the Qwen CLI. The logic is similar to that of Gemini, but it automatically converts local files to data URLs for the CLI to read when necessary.

Configuration

Copy .env.example for configuration. Common entries include:

• GEMINI_CLI_COMMAND / QWEN_CLI_COMMAND: Path to the CLI executable.
• GEMINI_DEFAULT_MODEL / QWEN_DEFAULT_MODEL: Default model name.
• GEMINI_OUTPUT_FORMAT: Control the Gemini output (text or json).
• MCP_COMMAND_TIMEOUT_MS: Global timeout (in milliseconds).
• MCP_MAX_IMAGE_BYTES: Maximum allowed image size.
• MCP_ALLOWED_IMAGE_EXTENSIONS: List of allowed file extensions.
• MCP_IMAGE_TEMP_DIR: Directory to store temporary files after download/decoding.

If you need to override the CLI command for a single invocation, you can provide cliPath in the tool parameters (supported by both Gemini and Qwen).

Local Diagnostics

The project provides two simple scripts to manually verify CLI invocations:

npx tsx scripts/dev/manual-gemini-test.ts
npx tsx scripts/dev/manual-qwen-test.ts

Ensure that npm run build has been completed or use ts-node/tsx before execution.

Project Structure

src/
  index.ts                 # Program entry point, load env and start the MCP server
  config/                  # Configuration parsing (appConfig, etc.)
  providers/               # CLI provider adaptation layer (Gemini/Qwen)
  server/                  # MCP server wiring
  tools/                   # MCP tool definition and registration
  utils/                   # Common tools for file, CLI scheduling, etc.
scripts/
  dev/                     # Manual verification scripts
test-assets/               # Example image resources

Roadmap

• ✅ Image analysis with Gemini CLI
• ✅ Image analysis with Qwen CLI (including automatic data URL conversion)
• ⏳ Resource list and more multimodal providers
• ⏳ Automated testing and lint/format pipeline

📄 License

This project is under the MIT License. Contributions via issues/PRs are welcome.

Acknowledgements

• Model Context Protocol
• Google Gemini CLI
• @qwen-code/qwen-code