deepseek-vision-mcp

Gives text-only coding agents — DeepSeek in Reasonix, Claude Code, Cursor, Claude Desktop, or any MCP client — the ability to look at images. It adds two tools:

• describe_image(path, question) — sends the file to Gemini Flash and returns a detailed text description: transcribed text, layout, UI elements, error messages.

• describe_ui(path) — structured UI report for a screenshot of a user interface (app window, web page, game menu): ASCII layout wireframe, element inventory (label | role | approx x%,y% | size | state) with exact visible text, and short visual notes. Prefer this when you need layout, positions and states, not prose.

Install

1. Install uv (skip if you have it — check with uv --version):

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Register the server, globally — Reasonix stores CLI-installed servers in its user-level config.toml, so this covers every project:

reasonix mcp add vision -- uvx --from git+https://github.com/DIV7NE/deepseek-vision-mcp vision-mcp

Expect added MCP server "vision" — ready with 2 tools. See Startup warnings if you also get WARN plugin: start auxiliary ….

For a single project instead, cd there first — a new terminal often starts in a system folder you can't write to:

cd C:\path\to\your\project
uvx --from git+https://github.com/DIV7NE/deepseek-vision-mcp vision-mcp --install

That writes .mcp.json in the current folder, keeping any servers already listed. Pass a path to target another client's config, creating it if needed:

uvx --from ... vision-mcp --install "$env:APPDATA\Claude\claude_desktop_config.json"

vision-mcp --global runs the Reasonix command for you when the reasonix CLI is on PATH, and prints the equivalent for other clients when it isn't.

3. Set your API key. Get a free one at https://aistudio.google.com/apikey. The server reads GEMINI_API_KEY from its environment, and your MCP client passes its environment down to the servers it launches:

# Windows
setx GEMINI_API_KEY your-key-here

# macOS / Linux — add to ~/.zshrc or ~/.bashrc
export GEMINI_API_KEY=your-key-here

setx only affects processes started afterwards, so close the terminal and fully quit your MCP client, then reopen both. Check it took with echo $env:GEMINI_API_KEY.

To let Reasonix hold the key instead of your user profile, re-add the server with it attached — Reasonix treats these values as credentials and keeps them out of the server's identity fingerprint:

reasonix mcp add vision --env GEMINI_API_KEY=your-key-here -- uvx --from git+https://github.com/DIV7NE/deepseek-vision-mcp vision-mcp

Related MCP server: vision-mcp

Usage

Ask your agent:

use describe_image on C:\path\to\screenshot.png and tell me what the error says

Pass a question to ask something specific rather than getting a general description.

For screenshots of an interface — app windows, web pages, game menus — ask for the structured report instead:

use describe_ui on C:\path\to\screenshot.png and tell me where the PLAY button is

describe_ui returns the layout wireframe, every element with its approximate position and state (selected/hover/active), and exact visible text.

Agent skill

skills/describe-ui/SKILL.md is a drop-in agent skill for clients that support them (Reasonix, Claude Code, Cursor). It tells the agent to prefer describe_ui for screenshots of interfaces and falls back to the structured prompt through describe_image when the running server is stale. Copy it into your client's skill directory, or install it globally with the client's own skill installer (Reasonix: install_skill with scope: global).

Uninstall

Remove the global install:

reasonix mcp remove vision

Remove it from one project — run in that folder, or pass a config path:

uvx --from git+https://github.com/DIV7NE/deepseek-vision-mcp vision-mcp --uninstall

Both leave every other server in place, and vision-mcp --uninstall --global runs the Reasonix command for you. Global and project entries are separate, so remove both if you installed both. Restart your client afterwards.

The downloaded package stays in uv's cache; uv cache clean clears it. The API key stays in your environment until you remove it (setx GEMINI_API_KEY "" on Windows).

Troubleshooting

Startup warnings. WARN plugin: start auxiliary prompt client failed … context canceled and the matching resource line are harmless. Reasonix starts separate optional clients to fetch a server's prompts and resources; this server offers neither, and the short-lived CLI process cancels their context as it exits. The line that matters is ready with 2 tools — a real failure would report zero.

PermissionError writing .mcp.json. You ran --install from a folder you can't write to, usually C:\Windows\System32 where PowerShell starts. cd to your project first, or pass a config path.

uvx not found on PATH. The MCP client (Reasonix, Claude Desktop) spawns stdio servers with a fixed PATH that usually does not include uv's bin directory (~/.local/bin after the astral installer), so command = "uvx" fails to launch even though uvx works in your terminal. Fix: set command to the absolute path (C:\Users\<you>\.local\bin\uvx.exe on Windows) or add that directory to the server's PATH env in the client config. --install and the PowerShell installer write the resolved absolute path automatically when uvx is on your shell PATH.

A global install seems ignored. Project config wins: a vision entry in a project's .mcp.json or reasonix.toml overrides the global one. Delete the project entry.

Changes don't appear. Reasonix applies CLI config changes on the next session, so restart it. Inside a running chat, /mcp add connects immediately instead.

404 mentioning the model. Set GEMINI_MODEL to a current model ID from https://ai.google.dev/gemini-api/docs/models.

Manual config

If you prefer editing config yourself, this is the entry --install writes:

{
  "mcpServers": {
    "vision": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/DIV7NE/deepseek-vision-mcp", "vision-mcp"]
    }
  }
}

uvx needs git available on PATH to fetch the repo; no GitHub account is required.

The command field is the absolute uvx path when the installer could resolve one (see uvx not found on PATH); edit it back to a bare uvx only if your client's launch PATH includes uv's bin directory.

Notes

• The key is read from GEMINI_API_KEY and never written into a config file.

• The model defaults to gemini-3.6-flash, current per Google's model docs; override with a GEMINI_MODEL env var.

• The MCP SDK is pinned to 2.0.0, which renamed FastMCP to MCPServer. An unpinned upgrade breaks the server.

• Gemini's free tier is generous (about 10 requests a minute) but may use submitted data for training, so don't send screenshots containing secrets unless billing is enabled.

• Images must be PNG, JPEG, GIF, WebP or BMP, and under 15MB.

• The agent reasons over Gemini's description, not the pixels: reliable for text, errors, and layout, unreliable for pixel-level visual judgment.

• install-vision-mcp.ps1 does every step at once on Windows, including installing uv and prompting for the key.