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

---

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:

Field	Description
answer	Direct answer to your question
description	Comprehensive visual description of the image
objects	List of detected objects
uncertainties	Ambiguities or low-confidence details

---

Supported Image Formats

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

---

Troubleshooting

Error	Solution
GEMINI_API_KEY is not configured	Verify your .env file contains a valid API key
Image file does not exist	Double check the image path
python is not recognized	Reinstall Python and make sure to check "Add to PATH"
Claude Desktop says "This repository isn't a marketplace"	Make sure you added the marketplace URL https://github.com/tqctqc1/deepseek-vision-mcp (the .claude-plugin/marketplace.json manifest lives at the repo root)
Claude Desktop does not show the tool	Verify config paths / setup steps and restart Claude Desktop
MCP tool vision_analyze is missing	The plugin MCP server failed to start — run the venv setup in the installed plugin directory and confirm .env exists there