Skip to main content
Glama

mcp-see

An MCP server that gives AI agents eyes - the ability to observe and understand images without stuffing raw pixels into their context window.

Features

  • Multi-provider vision: Describe images using Gemini, OpenAI, or Claude

  • Object detection: Find objects with bounding boxes (Gemini only - native bbox support)

  • Hierarchical analysis: Detect regions, then zoom in for detail

  • Precise color extraction: K-Means clustering in LAB color space (runs locally, no API needed)

  • Color naming: Human-readable color names via color.pizza API

  • URL support: Analyze images directly from the web (http/https)

TL;DR: A Gemini API key gives you full functionality. OpenAI/Claude are optional alternatives for image description only.

Related MCP server: VisionPower

Installation

Install from npm:

npx @sanity-labs/mcp-see

Or install globally:

npm install -g @sanity-labs/mcp-see

Or clone and build locally:

git clone https://github.com/sanity-labs/mcp-see.git
cd mcp-see
npm install
npm run build

MCP Client Configuration

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "mcp-see": {
      "command": "npx",
      "args": ["@sanity-labs/mcp-see"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key"
      }
    }
  }
}

Get your Gemini API key from Google AI Studio.

With all providers (optional):

{
  "mcpServers": {
    "mcp-see": {
      "command": "npx",
      "args": ["@sanity-labs/mcp-see"],
      "env": {
        "GEMINI_API_KEY": "your-gemini-api-key",
        "OPENAI_API_KEY": "sk-...",
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}

Enterprise/Vertex AI users:

{
  "mcpServers": {
    "mcp-see": {
      "command": "npx",
      "args": ["@sanity-labs/mcp-see"],
      "env": {
        "GOOGLE_CLOUD_PROJECT": "your-gcp-project-id"
      }
    }
  }
}

Requires ADC setup: gcloud auth application-default login

Other MCP Clients

The server runs on stdio transport. Configure your client to spawn npx @sanity-labs/mcp-see.

Tools

describe

Get an AI-generated description of an image.

Input:

{
  "image": "/path/to/image.png or https://example.com/image.jpg",
  "prompt": "What is shown in this image?",
  "provider": "gemini",
  "detail": "detailed"
}

Example Output:

The image shows a vibrant and colorful salad bowl, viewed from directly above.
The bowl is made of a light brown, possibly biodegradable material. The salad
is composed of various ingredients arranged in distinct sections: two small
white peeled eggs, sliced red tomatoes topped with chopped green onions, cubed
seasoned tofu, bright green edamame beans, shredded purple cabbage, and
julienned carrots...

detect

Detect objects and return bounding boxes. Uses Gemini for native bbox support.

Input:

{
  "image": "/path/to/image.png",
  "prompt": "find all TV screens"
}

Example Output:

{
  "count": 3,
  "objects": [
    { "id": 1, "label": "television", "bbox": [178, 245, 433, 818] },
    { "id": 2, "label": "television", "bbox": [614, 518, 792, 898] },
    { "id": 3, "label": "television", "bbox": [617, 198, 792, 493] }
  ]
}

Coordinates are [ymin, xmin, ymax, xmax] normalized 0-1000.

describe_region

Crop to a bounding box and describe that region in detail.

Input:

{
  "image": "/path/to/image.png",
  "bbox": [200, 200, 800, 800],
  "prompt": "describe this in detail",
  "provider": "gemini"
}

Example Output:

{
  "bbox": [200, 200, 800, 800],
  "description": "The image showcases a vibrant and colorful salad bowl in close-up. The bowl contains fresh ingredients including cubed tofu with a seasoned exterior, bright green edamame, sliced tomatoes, and shredded purple cabbage..."
}

analyze_colors

Extract dominant colors from a region using K-Means clustering in LAB color space.

Input:

{
  "image": "/path/to/image.png",
  "bbox": [100, 200, 400, 600],
  "top": 5
}

Example Output:

{
  "dominant": [
    {
      "hex": "#e6e6e5",
      "rgb": [230, 230, 229],
      "hsl": { "h": 60, "s": 2, "l": 90 },
      "name": "Ambience White",
      "percentage": 75.91
    },
    {
      "hex": "#b16c39",
      "rgb": [177, 108, 57],
      "hsl": { "h": 26, "s": 51, "l": 46 },
      "name": "Ginger Dough",
      "percentage": 15.91
    }
  ],
  "average": {
    "hex": "#c4b8a8",
    "rgb": [196, 184, 168],
    "name": "Doeskin"
  },
  "confidence": "high",
  "region": {
    "bbox": [100, 200, 400, 600],
    "size": [200, 150],
    "totalPixels": 30000
  }
}

The confidence field indicates color precision:

  • high: Flat colors (UI elements) - clusters are tight

  • medium: Mixed content

  • low: Photographs/gradients - colors are approximate

Workflows

Hierarchical Image Understanding

The power of mcp-see is in combining tools for progressive analysis:

1. describe(image)
   → "A shelf displaying various vintage electronics and TVs"

2. detect(image, "find all screens")
   → [{label: "television", bbox: [178, 245, 433, 818]}, ...]

3. describe_region(image, [178, 245, 433, 818])
   → "A vintage CRT television with wood grain casing, displaying
      a test pattern. The screen shows horizontal color bars..."

4. analyze_colors(image, [178, 245, 433, 818])
   → dominant: ["#2b1810" Espresso Bean, "#c4a882" Sandcastle, ...]

Design Reference Analysis

Extract implementation-ready specs from design mockups:

1. describe(image, "explain this UI to a web developer")
   → Layout structure, component hierarchy, spacing patterns

2. detect(image, "find all buttons")
   → Bounding boxes for each button

3. For each button:
   - describe_region() → Button label, icon, state
   - analyze_colors() → Exact color tokens for CSS

API Keys

Quick Start: Gemini Only

For full functionality, you only need a Gemini API key:

Variable

Description

GEMINI_API_KEY

Get one from Google AI Studio

This gives you access to all tools: describe, detect, describe_region, and analyze_colors.

Tool Availability by Provider

Tool

Gemini

OpenAI

Claude

No API

describe

✅

✅

✅

describe_region

✅

✅

✅

detect

✅

❌

❌

analyze_colors

✅

  • detect (object detection with bounding boxes) requires Gemini - it's the only provider with native bounding box support

  • analyze_colors runs locally using K-Means clustering - no API key needed

All Environment Variables

Variable

Required

Description

GEMINI_API_KEY

Recommended

API key from Google AI Studio. Enables all tools.

GOOGLE_CLOUD_PROJECT

Alternative

GCP project ID for Vertex AI instead of Gemini API. Requires ADC setup (gcloud auth application-default login).

OPENAI_API_KEY

Optional

OpenAI API key for GPT-4o vision. Alternative provider for describe and describe_region.

ANTHROPIC_API_KEY

Optional

Anthropic API key for Claude vision. Alternative provider for describe and describe_region.

If both GEMINI_API_KEY and GOOGLE_CLOUD_PROJECT are set, GEMINI_API_KEY takes precedence.

Technical Details

Color Extraction Algorithm

The analyze_colors tool uses K-Means clustering in LAB color space:

  1. Convert pixels from RGB to LAB (perceptually uniform)

  2. Subsample to 50k pixels for performance

  3. K-Means++ initialization for better convergence

  4. Cluster centroids become dominant colors

  5. Convert back to RGB, name via color.pizza API

This approach groups perceptually similar colors together, working well for both flat UI colors and noisy photographs.

Bounding Box Format

All bounding boxes use [ymin, xmin, ymax, xmax] format with coordinates normalized to 0-1000. To convert to pixel coordinates:

const pixelX = (normalizedX / 1000) * imageWidth;
const pixelY = (normalizedY / 1000) * imageHeight;

License

MIT

Available Tools

4 tools
analyze_colorsA

Extract dominant colors from an image region using K-Means clustering in LAB color space. Returns colors sorted by frequency with human-readable names from color.pizza.

Inputs: image (required), top, bbox.

describeC

Get an AI-generated description of an image. Supports multiple providers (Gemini, OpenAI, Claude).

Inputs: image (required), detail, prompt, provider.

describe_regionA

Crop an image to a bounding box and describe that region in detail. Use this after detect() to zoom in on specific objects.

Inputs: bbox (required), image (required), prompt, provider.

detectA

Detect objects in an image and return bounding boxes. Uses Gemini for native bounding box support. Coordinates are normalized 0-1000 as [ymin, xmin, ymax, xmax].

Inputs: image (required), prompt.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 4 tools

    Disambiguation4/5

    Each tool targets a distinct image analysis operation: full-image description, object detection, region-level description, and color extraction. The only slight overlap is between describe and describe_region, but the latter's description clarifies its use after detect().

    Naming Consistency4/5

    All names are snake_case and start with a verb, but the pattern is mixed: describe and detect are bare verbs while describe_region and analyze_colors follow verb_noun. This minor inconsistency is still readable.

    Tool Count5/5

    Four tools is a well-scoped set for an image analysis server, with each tool fulfilling a distinct role. The count is neither bloated nor thin.

    Completeness4/5

    The surface covers core image understanding: description, object detection, region zoom, and color analysis. However, notable gaps exist such as OCR/text extraction or image classification, which some users might expect from an 'mcp-see' server.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      MCP server that gives text-only AI agents the ability to understand images via vision tools, including multi-image analysis, OCR, comparison, and structured extraction. It uses providers like OpenAI, Anthropic, Gemini, and OpenRouter to return plain text descriptions.
      10
      18 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      An MCP server that adds visual understanding to text-only LLMs via image understanding, OCR, and image comparison tools, with multi-provider fallback and context-aware Focus Hint for precise descriptions.
      3
      MIT