MCP Image Resolver Server

An MCP (Model Context Protocol) server that provides royalty-free image search for AI hosts like Cursor, Claude Desktop, VS Code, Windsurf, and more. Ask your AI assistant to find images by natural language—it uses the search_images tool and returns structured results from Pexels and Unsplash.

Features

• search_images — Search for royalty-free images (supports limit, page, orientation)
• extract_image_query — Transform free-form text into an image search query
• get_best_image — Return a single best image for a query
• search_images_batch — Run multiple searches in parallel
• resolve_image_attribution — Generate provider-compliant attribution text
• Pexels & Unsplash — Multi-provider support (free tier for both)
• Unified response — Structured results with url, source, dimensions, photographer, tags
• Works everywhere — Any MCP client that supports stdio servers

Requirements

• Node.js 18+
• At least one API key: Pexels (pexels.com/api) and/or Unsplash (unsplash.com/oauth/applications)

Quick Start (No Installation Required)

No cloning or building needed. Just add this config to your MCP client and it runs via npx automatically:

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["-y", "@ahmaddioxide/mcp-image-resolver"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

At least one API key is required. Both are free — get them here:

• Pexels: pexels.com/api
• Unsplash: unsplash.com/oauth/applications

Architecture (High-Level)

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP Client (Cursor, Claude, VS Code, etc.)        │
│                                     │                                       │
│                            stdio (stdin/stdout)                             │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                                      ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│                         MCP Image Resolver Server                           │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  index.ts          MCP server entry, registers tools, stdio transport│   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│                                      ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │  tools/search-images.ts   Tool handler: search_images(query)         │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                      │                                      │
│                                      ▼                                      │
│  ┌──────────────────────┐  ┌──────────────────────┐                        │
│  │  providers/pexels.ts  │  │ providers/unsplash.ts │                        │
│  │  Pexels API adapter   │  │ Unsplash API adapter  │──▶ ImageResult schema  │
│  └──────────────────────┘  └──────────────────────┘                        │
│               │                        │                                    │
│               └────────────────────────┴────▶ utils/normalize.ts            │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌───────────────────────

... [View full README on GitHub](https://github.com/ahmaddioxide/image-resolver-mcp#readme)