# 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](#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
```

## 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:

```json
{
  "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](#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.