vision-mcp

An MCP server that helps non-vision models extract and understand images and screenshots via OpenRouter multimodal models.

Features

analyze_image — Send an image (local file or URL) with a text prompt to any OpenRouter vision model and get a natural-language response.
screen — Capture a screenshot of an application window by PID or process name (Windows only, uses PrintWindow via PowerShell).

Prerequisites

Node.js 18+ (ESM)
An OpenRouter API key with access to a vision-capable model

Setup

# Clone and install
git clone <your-repo>
cd vision-mcp
npm install

# Configure environment
cp .env.example .env

Edit .env and set your OpenRouter key and preferred model:

OPENROUTER_API_KEY=sk-or-v1-...
OPENROUTER_MODEL=google/gemini-2.0-flash-lite-preview-02-05:free

Environment variables

| Variable | Required | Default | Description | |---|---|---|---| | OPENROUTER_API_KEY | Yes | — | Your OpenRouter API key | | OPENROUTER_MODEL | Yes | — | Model identifier (e.g. google/gemma-4-31b-it:free) | | OPENROUTER_BASE_URL | No | https://openrouter.ai/api/v1 | API base URL override | | MAX_IMAGE_MB | No | 20 | Maximum allowed image size in MB |

Build & Run

npm run build
npm start

The server uses stdio transport and is designed to be launched by an MCP-enabled host (e.g. Claude, OpenCode). Example configuration block for your MCP client:

{
  "mcpServers": {
    "vision-mcp": {
      "command": "npx",
      "args": ["-y", "@forloopcodes/visionmcp"],
      "env": {
        "OPENROUTER_API_KEY": "sk-or-v1-...",
        "OPENROUTER_MODEL": "google/gemma-4-31b-it:free"
      }
    }
  }
}

Tools

`analyze_image`

Analyze an image using a vision model.

Arguments: | Name | Type | Required | Description | |---|---|---|---| | prompt | string | Yes | Instruction for the vision model | | image | string | Yes | Local file path or http/https URL |

Local images are loaded, validated (size, path scope), and sent as base64 data URIs. Remote URLs are passed through directly.

`screen`

Capture a screenshot of a running application window (Windows only).

Arguments: | Name | Type | Required | Description | |---|---|---|---| | action | "capture" | Yes | The capture action | | target | string | No | Process name to find and capture (e.g. wezterm, notepad) | | pid | number | No | Process ID to capture |

Provide either target or pid. The server uses PrintWindow via a compiled C# snippet invoked through PowerShell. Supports PW_RENDERFULLCONTENT for DPI-aware captures.

[!NOTE] Screen capture requires the System.Drawing assembly and works on Windows only. The captured PNG is written to the system temp directory.

Architecture

src/
├── server.ts          # MCP server entry point, tool routing
├── image.ts           # Image loading, validation, base64 encoding
├── openrouter.ts      # OpenRouter API client (multimodal chat completions)
├── types.ts           # Shared TypeScript interfaces for API payloads
└── screen/
    ├── index.ts       # Platform abstraction for screen capture
    └── windows.ts     # PowerShell + Win32 implementation (PrintWindow)

The server runs on the Model Context Protocol SDK with stdio transport. Image analysis requests are forwarded to OpenRouter's /chat/completions endpoint with a 60-second timeout. Security boundaries are enforced at the image loader — only files within the working directory are accepted.

Security

Local image paths are checked against the project root to prevent directory traversal.
Screen captures are written to the OS temp directory ($TMPDIR).
The PowerShell execution uses -ExecutionPolicy Bypass for the embedded C# script; no external .ps1 files are written to disk.

License

MIT

MCP Servers