DeepSeek Vision Bridge

A visual perception bridge enabling text-only AI models (such as DeepSeek) to see and read images via Google Gemini.

When sending images to a model that lacks vision capabilities, this tool automatically forwards the image to Gemini for visual analysis and returns structured text results for the AI model to process.

Prerequisites

• Python 3.10+ — Download from python.org (Make sure to check "Add Python to PATH" during installation)

• Free Gemini API Key — Obtain from aistudio.google.com/apikey

Related MCP server: GeminiMcpServer

Installation

Step 1: Clone the Repository

Open PowerShell (press Win + R, type powershell, and press Enter) and run:

git clone https://github.com/tqctqc1/deepseek-vision-mcp.git
cd deepseek-vision-mcp

If Git is not installed, download it from git-scm.com or click Code -> Download ZIP on GitHub, extract it, and open PowerShell inside the folder.

Step 2: Install Dependencies & Bootstrap (Self-Healing)

Run the one-command bootstrap script in PowerShell:

powershell -ExecutionPolicy Bypass -File .\ensure_env.ps1

Or via CLI:

python vision_cli.py --setup

This automatically creates .venv, installs dependencies, sets up .env, and verifies environment health.

Check environment health (<1s check):

python vision_cli.py --health --pretty

Step 3: Configure API Key

Copy-Item .env.example .env

Open .env in Notepad and replace put-your-key-here with your Gemini API key:

GEMINI_API_KEY=AIzaSy...your-api-key...

Save the file. Do not share your .env file publicly.

Usage

Option 1: Command-Line Interface (CLI)

Analyze a local image:

python vision_cli.py --image-path "C:\path\to\image.png" --question "Describe the contents of this image." --pretty

Analyze an image from a URL:

python vision_cli.py --image-url "https://example.com/image.jpg" --question "Transcribe text in this image." --pretty

Option 2: Integration with Claude Desktop (plugin marketplace)

This repository is a Claude plugin marketplace. In Claude Desktop:

1. Open Settings -> Plugins -> Add marketplace and paste: https://github.com/tqctqc1/deepseek-vision-mcp

2. Click Sync, then install the deepseek-vision plugin.

3. Claude copies the plugin to a managed directory. Run the 1-command bootstrap inside that plugin directory:

   powershell -ExecutionPolicy Bypass -File .\ensure_env.ps1

   Then put your Gemini API key in .env.

4. Restart Claude Desktop and confirm the vision_analyze tool appears.

Requires python to be on your PATH. If you prefer manual MCP configuration instead, follow Option 3.

Option 3: Integration with Claude Desktop (manual MCP)

Open the Claude Desktop configuration file:

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Add the following under mcpServers (update the paths to match your installation directory):

{
  "mcpServers": {
    "deepseek-vision": {
      "command": "C:\\path\\to\\deepseek-vision-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\deepseek-vision-mcp\\server.py"],
      "env": { "PYTHONUTF8": "1" }
    }
  }
}

Save the file, exit Claude Desktop completely, and reopen it.

Option 4: Integration with Codex

Install the marketplace, then the plugin:

codex marketplace add tqctqc1/deepseek-vision-mcp
codex plugin install deepseek-vision@deepseek-vision-mcp

The Codex plugin bundles skills that tell the agent to use the vision_analyze MCP tool, with a CLI fallback (vision_cli.py) when the MCP server is unavailable. Like other marketplace installs, the plugin cache does not include a venv — create it in the installed plugin directory if the CLI fallback is needed:

python -m venv --system-site-packages "$env:USERPROFILE\.codex\plugins\cache\deepseek-vision-mcp\deepseek-vision\1.0.0\.venv"

Output Format

The tool returns a JSON object containing 4 fields:

Supported Image Formats

PNG, JPEG, WebP, HEIC, HEIF — up to 10 MB.

Troubleshooting