Fazee Vision MCP Server

Production-grade MCP server for advanced image and screenshot analysis with a Gemini-first provider strategy.

Features

• Gemini as primary/default provider
• Provider fallback chain: Gemini -> OpenRouter -> Ollama
• vision_analyze MCP tool with strict Zod validation
• Secure image ingestion: URL, local path, file:// URL, base64, data URL
• Security protections: SSRF defense, private IP blocking, safe local path allowlist, size/pixel limits
• Sharp-based preprocessing: EXIF fix, resize, compression, normalization, metadata extraction, hashing
• Typed errors and stable error codes
• In-memory TTL caching keyed by image hash + prompt + provider/model/mode
• Text and JSON output formats
• Strict TypeScript + Vitest tests

Project Structure

src/
  index.ts
  server.ts
  config.ts
  schemas.ts
  errors.ts

  image/
    loadImage.ts
    security.ts
    normalize.ts
    types.ts

  providers/
    base.ts
    gemini.ts
    openrouter.ts
    ollama.ts

  services/
    visionService.ts
    prompts.ts

  cache/
    memoryCache.ts

  utils/
    logger.ts
    timing.ts

tests/
  security.test.ts
  imageInput.test.ts
  cache.test.ts
  providerMock.test.ts
  toolContract.test.ts

Installation

npm install

Environment Setup

Create .env:

VISION_PROVIDER=gemini
GEMINI_API_KEY=
GEMINI_MODEL=gemini-2.5-flash

OPENROUTER_API_KEY=
OPENROUTER_MODEL=google/gemini-2.5-flash

OLLAMA_BASE_URL=http://127.0.0.1:11434
OLLAMA_MODEL=llava

VISION_MAX_IMAGE_MB=12
VISION_MAX_PIXELS=40000000
VISION_ALLOWED_LOCAL_ROOTS=
VISION_ENABLE_URL_INPUT=true
VISION_ENABLE_LOCAL_PATH_INPUT=false

VISION_CACHE_ENABLED=true
VISION_CACHE_TTL_SECONDS=300
VISION_LOG_LEVEL=info
VISION_REQUEST_TIMEOUT_MS=30000

Provider Setup

Gemini (Primary)

1. Create API key in Google AI Studio.
2. Set GEMINI_API_KEY.
3. Optional: set GEMINI_MODEL.

OpenRouter

1. Create OpenRouter API key.
2. Set OPENROUTER_API_KEY and optional OPENROUTER_MODEL.

Ollama (Local)

1. Install/start Ollama locally.
2. Pull a vision model (example: ollama pull llava).
3. Set OLLAMA_BASE_URL and OLLAMA_MODEL.

Run

npm run dev

Build:

npm run build
node dist/index.js

MCP Client Config

Claude Code (npx)

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "fazee-vision-mcp@latest"],
      "env": {
        "VISION_PROVIDER": "openrouter",
        "OPENROUTER_API_KEY": "your_key",
        "OPENROUTER_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

Cursor (npx)

{
  "mcpServers": {
    "vision": {
      "command": "npx",
      "args": ["-y", "fazee-vision-mcp@latest"],
      "env": {
        "VISION_PROVIDER": "openrouter",
        "OPENROUTER_API_KEY": "your_key",
        "OPENROUTER_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

Generic MCP (npx)

{
  "name": "vision",
  "command": "npx",
  "args": ["-y", "fazee-vision-mcp@latest"],
  "env": {
    "VISION_PROVIDER": "openrouter",
    "OPENROUTER_API_KEY": "your_key",
    "OPENROUTER_MODEL": "gemini-2.5-flash-lite"
  }
}

Publish To npm

npm run typecheck
npm test
npm run build
npm login
npm publish --access public

Tool API

Tool: vision_analyze

Input:

• imageSource: URL | local path | file:// URL | base64 | data URL
• prompt: analysis instruction
• mode: general | palette | hierarchy | components | ocr | ui_analysis | code_screenshot
• options: temperature, maxTokens, outputFormat, provider, model, enableCache, timeoutMs

Troubleshooting

• CONFIG_ERROR: missing provider credentials and local provider unavailable
• SECURITY_ERROR: URL/path blocked by security policy
• INPUT_ERROR: invalid image source or limits exceeded
• TIMEOUT_ERROR / PROVIDER_ERROR: provider request exceeded timeout or failed

For local files, set both:

VISION_ENABLE_LOCAL_PATH_INPUT=true
VISION_ALLOWED_LOCAL_ROOTS=C:\Users\name\Pictures,C:\Users\name\AppData\Local\Temp

Use VISION_ALLOWED_LOCAL_ROOTS=* only for a fully trusted local setup.

Security Notes

• Blocks localhost/private/metadata targets for URL image fetching
• Enforces local path allowlist for filesystem image access unless VISION_ALLOWED_LOCAL_ROOTS=*
• Enforces image byte and pixel limits
• Prevents secret leakage by avoiding raw secret logging

Windows Setup

Do not set command to a .js file directly on Windows.
If command is a .js path, Windows will show "Select an app to open this .js file".

Use one of these two safe options:

1. command: "node" + JS path in args (recommended)
2. command: "cmd" + the included launcher script (scripts\\run-vision-mcp.cmd)

Example (local project):

{
  "mcpServers": {
    "vision": {
      "command": "node",
      "args": ["C:\\\\Users\\\\name\\\\project\\\\dist\\\\index.js"],
      "env": {
        "VISION_PROVIDER": "openrouter",
        "OPENROUTER_API_KEY": "your_key",
        "OPENROUTER_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

If Node is not in PATH, use full path: C:\\Program Files\\nodejs\\node.exe

Alternative launcher config (avoids .js association issues in strict clients):

{
  "mcpServers": {
    "vision": {
      "command": "cmd",
      "args": ["/d", "/c", "C:\\\\Users\\\\name\\\\project\\\\scripts\\\\run-vision-mcp.cmd"],
      "env": {
        "VISION_PROVIDER": "openrouter",
        "OPENROUTER_API_KEY": "your_key",
        "OPENROUTER_MODEL": "gemini-2.5-flash-lite"
      }
    }
  }
}

Linux Setup

• Use absolute Linux paths in MCP config, for example: /home/name/project/dist/index.js

Test

npm test
npm run typecheck