CV-MCP Server

Provides image captioning and metadata generation for images via OpenRouter or local backends.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "samhains-cv-mcp": {
      "command": "cv-mcp-server",
      "args": [],
      "env": {
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_API_KEY"
      }
    }
  }
}

This MCP server provides a compact, composable way to perform computer vision analysis and generate metadata for images. You can caption images from a URL or a local file, then optionally produce structured metadata and alt text for accessibility, all through a lightweight,_stdio-based MCP interface.

How to use

You run the MCP server locally and connect your MCP client to it. The server exposes tools that let you caption an image, generate alt text, create detailed captions, and produce structured image metadata. The typical flow is to start the server, then call the captioning and metadata tools with either an image URL or a local file path. You can control which backend is used for each step (OpenRouter or a local model) and can override this on a per-call basis.

Use the standard MCP stdio server entry point to start the server. Once running, your MCP client should connect to the stdio endpoint you configured.

How to install

Prerequisites: Python 3.8+ and a working Python environment.

Install the package in editable mode so you can modify the code locally.

pip uninstall -y cv-mcp  # if you have a published version installed
pip install -e .

Configuration and usage notes

Environment variables: you provide an OpenRouter API key via OPENROUTER_API_KEY for image analysis and metadata generation that rely on the OpenRouter backend.

Run the MCP server as a stdio server using the console script cv-mcp-server. Configure your MCP client to launch cv-mcp-server.

Quick tests and examples

Test captioning for an image URL or a local file path. Use the CLI helper if you want a quick local check.

# URL test
python cli/caption_image.py --image-url https://example.com/img.jpg

# Local file test
python cli/caption_image.py --file-path ./image.jpg

Troubleshooting and tips

A 401/403 from OpenRouter usually means the API key is missing or invalid. Ensure OPENROUTER_API_KEY is set and reachable from your environment.

If you use local backends, install optional dependencies to enable local model support, and ensure the required models are cached or available locally.

Available tools

caption_image

One-off capture of a caption for an image from a URL or local file, kept for compatibility with the CLI.

alt_text

Generate a short alt text (≤ 20 words) for accessibility.

dense_caption

Produce a detailed 2–6 sentence caption for the image.

image_metadata

Return structured metadata including alt_text, caption, and a metadata field. Supports modes: double (vision then text) and triple (vision twice, text).