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