# 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](https://www.python.org/downloads/) (Make sure to check **"Add Python to PATH"** during installation)
- **Free Gemini API Key** — Obtain from [aistudio.google.com/apikey](https://aistudio.google.com/apikey)

---

## Installation

### Step 1: Clone the Repository

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

```powershell
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](https://git-scm.com/downloads) 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
powershell -ExecutionPolicy Bypass -File .\ensure_env.ps1
```

Or via CLI:

```powershell
python vision_cli.py --setup
```

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

Check environment health (<1s check):

```powershell
python vision_cli.py --health --pretty
```

### Step 3: Configure API Key

```powershell
Copy-Item .env.example .env
```

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

```env
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:

```powershell
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:

```powershell
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
   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:

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

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

```json
{
  "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:

```powershell
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:

```powershell
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 |