vision-opencode-mcp

Give opencode (or any MCP client) visual reference by calling an OpenAI-compatible vision model API. Exposes one tool:

• vision_describe(image_path?, question?) — read a local image and return what the vision model sees. When image_path is omitted, it automatically picks the newest image (by LastWriteTime) from the pasted-images dir, which is where opencode stores clipboard-pasted images.

Requires only python>=3.10 and the mcp SDK (installed automatically).

Requirements

• Python 3.10+

• A VISION_API_KEY for an OpenAI-compatible vision endpoint (base URL and model are baked in as defaults; override if needed)

Related MCP server: mcp-vision

Install

# from this repo
python -m venv .venv
# Windows:
.venv\Scripts\pip install -e .
# macOS/Linux:
# .venv/bin/pip install -e .

# or with uv (faster)
uv sync

This installs the vision-mcp console script and all dependencies (mcp, which pulls in mcp-types).

Configure for opencode

Add an mcp entry to your opencode config (opencode.json or ~/.config/opencode/opencode.json):

{
  "mcp": {
    "vision": {
      "type": "local",
      "command": [
        "C:\\path\\to\\vision-opencode-mcp\\.venv\\Scripts\\python.exe",
        "C:\\path\\to\\vision-opencode-mcp\\server.py"
      ],
      "enabled": true,
      "environment": {
        "VISION_API_KEY": "your-api-key-here"
      }
    }
  }
}

If you installed with uv sync, you can also point at the vision-mcp console script instead of the venv python:

{
  "mcp": {
    "vision": {
      "type": "local",
      "command": ["C:\\path\\to\\vision-opencode-mcp\\.venv\\Scripts\\vision-mcp.exe"],
      "enabled": true,
      "environment": {
        "VISION_API_KEY": "your-api-key-here"
      }
    }
  }
}

Restart opencode. The vision_describe tool then appears under the vision MCP server.

Environment variables

Usage

With image_path:

call vision_describe  image_path="D:\pics\shot.png"  question="这个截图里报了什么错？"

Without image_path (auto-picks the newest pasted image):

call vision_describe  question="这张图片里有什么？"

CLI (debug)

The repo also ships vision.py, a small command-line version of the same call:

python vision.py <image_path> [question]

Prints the model text to stdout; exits 0 on success, 1 on error (prints ERROR: ...). It reads the same environment variables as the server.

Notes

• The API key is read from the environment only — it never appears in the code, so this repo is safe to share.

• For clipboard-pasted images in opencode desktop, the tool auto-picks the newest file under the pasted-images dir, so you can just say "看这张图" and the tool picks it up.