Ollama Vision MCP

A Python MCP server that gives vision capabilities to a text-only LLM. It exposes a single tool, analyze_image, that sends a local image to a vision-capable Ollama model and returns the model's textual description.

Works with Claude Code, Cursor, and any MCP client that can launch a stdio command.

Motivation

deepseek-v4-flash:0731 is fast and capable, but it is a text-only model — it has no vision capability, so it can't look at screenshots, UI bugs, or diagrams on its own. Rather than switch to a heavyweight vision model for every task, this server bridges the gap: when the text-only LLM needs to "see" an image, analyze_image sends it to a vision-capable Ollama model (kimi-k2.6 by default — served by Ollama Cloud or a local instance) and returns the visual details as text the text-only model can then reason about.

Prerequisites

• Python 3.10+ with uv (recommended) or pip
• Access to an Ollama instance serving a vision model — either:

  • Ollama Cloud (no local daemon): export OLLAMA_HOST=https://ollama.com and OLLAMA_API_KEY=<your key> in your shell profile, or

  • a local Ollama with a vision model pulled:

    ollama serve &
    ollama pull kimi-k2.6
    

Quick start

# 1. Get the code
git clone https://github.com/wzul/ollama-vision-mcp.git
cd ollama-vision-mcp

# 2. Install dependencies
uv sync

# 3. Test it standalone
uv run python tests/test_e2e.py

Then register the server in your MCP client. For Claude Code, the CLI registers it at user scope (available in every project):

claude mcp add --scope user ollama-vision-mcp -- /absolute/path/to/ollama-vision-mcp/.venv/bin/ollama-vision-mcp

Scope gotcha: without --scope user, claude mcp add registers at the project-local scope only — the tool silently won't load from other directories.

Or add this to the top-level mcpServers object in ~/.claude.json (the top-level object is the user scope; see Registering):

"ollama-vision-mcp": {
  "command": "uvx",
  "args": ["--from", "/absolute/path/to/ollama-vision-mcp", "ollama-vision-mcp"]
}

💡 Easiest install: if you have Claude Code, just ask it to run the install-ollama-vision-mcp skill (ships in .claude/skills/ in this repo) — it checks prerequisites, writes the config, and verifies the connection for you.

Running as an MCP server (stdio)

uv run ollama-vision-mcp

or directly from source:

.venv/bin/python ollama_vision_mcp/server.py

Tool: analyze_image

Argument	Type	Required	Default
image_path	string	yes	— (absolute or relative path; PNG, JPG, WebP, …)
prompt	string	no	Describe this image in detail for a coding context.
model	string	no	kimi-k2.6

Logic: validates the path exists → opens the image with Pillow (normalized to RGB/PNG) → sends it base64-encoded alongside the prompt via ollama.chat() → returns the model's text response.

Registering in ~/.claude.json

Add an mcpServers entry for this server (replace /path/to/ollama-vision-mcp with your actual clone location). Two options:

Option A — uvx (runs in an isolated ephemeral environment)

{
  "mcpServers": {
    "ollama-vision-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "/path/to/ollama-vision-mcp",
        "ollama-vision-mcp"
      ]
    }
  }
}

uvx builds the local project each launch (cached). If the package is published to PyPI, "--from", "ollama-vision-mcp" works instead.

Option B — standard Python execution (existing project venv)

{
  "mcpServers": {
    "ollama-vision-mcp": {
      "command": "/path/to/ollama-vision-mcp/.venv/bin/python",
      "args": [
        "/path/to/ollama-vision-mcp/ollama_vision_mcp/server.py"
      ]
    }
  }
}

For a system-wide Python instead of the project venv, install the package first (uv tool install --from . ollama-vision-mcp or pip install .) and point command at the ollama-vision-mcp executable.

JSON gotcha: ~/.claude.json is a single big JSON object. The mcpServers block already exists — add the server as a new key inside it, and make sure you don't leave a trailing comma after the last entry.

Scope gotcha: the top-level mcpServers object is the user scope (available in every project). If you register via the CLI instead, pass --scope user — claude mcp add defaults to the project-local scope, which only loads when Claude Code starts from that project's directory.

Ollama Cloud: the server reads OLLAMA_HOST (default http://localhost:11434) and OLLAMA_API_KEY from the environment. For the cloud, export OLLAMA_HOST=https://ollama.com in your shell profile — no local daemon or ollama pull needed. The default model is kimi-k2.6 (the :cloud tag does not exist on the cloud catalog).

After editing, restart Claude Code (or reload MCP servers). The analyze_image tool will then be available to the text-only LLM.

Testing

uv run python tests/test_e2e.py

Spawns the server over stdio via mcp.client.stdio, verifies tool registration, runs analyze_image against a locally generated test image with both the default and a custom prompt, and checks error handling for a missing file.

License

MIT