Skip to main content
Glama
ahmaddioxide

MCP Image Resolver

by ahmaddioxide
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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

Related MCP server: unsplash-mcp

Requirements

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:

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            │
└─────────────────────────────────────┼───────────────────────────────────────┘
                                      │
                    ┌─────────────────┴─────────────────┐
                    ▼                                   ▼
┌──────────────────────────────┐    ┌──────────────────────────────────────────┐
│  Pexels API                  │    │  Unsplash API                             │
│  api.pexels.com              │    │  api.unsplash.com                         │
└──────────────────────────────┘    └──────────────────────────────────────────┘

Flow: MCP client → stdio → index.ts (registers tools) → search-images.ts → Pexels and Unsplash providers (when keys are set). Results are merged (Pexels first, then Unsplash) and normalized to the unified ImageResult schema.

Client Setup

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "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"
      }
    }
  }
}

Restart Cursor after config changes.

Claude Desktop

Add to your Claude config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

Via Settings: Developer → Edit Config

{
  "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"
      }
    }
  }
}

Restart Claude Desktop completely after saving.

VS Code

Add to .vscode/mcp.json (workspace) or your user profile mcp.json:

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

Note: VS Code uses servers (not mcpServers) and requires "type": "stdio".

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "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"
      }
    }
  }
}

Refresh the MCP config after changes.

Other MCP Clients

Any client that supports stdio MCP servers (Amp, Continue.dev, Amazon Q, etc.) can use this server:

  • Command: npx

  • Args: ["-y", "@ahmaddioxide/mcp-image-resolver"]

  • Env: { "PEXELS_API_KEY": "your-key", "UNSPLASH_ACCESS_KEY": "your-key" } (at least one required)

Usage

Once configured, ask your AI assistant to find images in natural language. It will call the search_images tool automatically.

Example prompts:

  • "Find royalty-free images of a sunset mosque"

  • "Search for zen yoga images suitable for a wellness app"

  • "Get some minimalist office workspace photos"

  • "Find images for a cooking blog header"

The tool returns image URLs and metadata. Use the links to view or download images.

Tool Schema

Tool

Params

Description

search_images

query, limit?, page?, orientation?

Search images from Pexels and Unsplash

extract_image_query

context

Extract search terms from free-form text

get_best_image

query, orientation?

Return a single best image

search_images_batch

queries, limit?

Run multiple searches in parallel

resolve_image_attribution

photographer, source, url?

Generate attribution text

Response: JSON with results array of { url, source, width, height, photographer, tags }. Each result includes source ("Pexels" or "Unsplash") for attribution.

Note: When both providers are configured, results are merged with Pexels first, then Unsplash. Use limit: 20 or higher to see results from both providers in a single search.

Testing

Example prompts to verify the tools:

  • "Search for mountain landscape with limit 20 and show me which results came from Pexels vs Unsplash."

  • "Use extract_image_query on: I need a hero image for a meditation app with mountains."

  • "Use search_images_batch for 'sunset mosque', 'pakistani flag', and 'zen yoga'."

  • "Get a single best image for coffee shop and generate attribution for it."

Development

To contribute or run locally, clone the repo and build from source:

git clone https://github.com/ahmaddioxide/image-resolver-mcp.git
cd image-resolver-mcp
npm install
cp .env.example .env
# Add PEXELS_API_KEY and/or UNSPLASH_ACCESS_KEY to .env
npm run build

Or run in development mode without building, using tsx:

{
  "mcpServers": {
    "image-resolver": {
      "command": "npx",
      "args": ["tsx", "/path/to/image-resolver-mcp/src/index.ts"],
      "env": {
        "PEXELS_API_KEY": "your-pexels-api-key",
        "UNSPLASH_ACCESS_KEY": "your-unsplash-access-key"
      }
    }
  }
}

Attribution

Images are sourced from Pexels and Unsplash. Per their API terms:

  • Provide prominent links to Pexels and Unsplash

  • Credit photographers: "Photo by [Name] on Pexels" / "Photo by [Name] on Unsplash"

  • Response metadata includes photographer and source; use resolve_image_attribution for compliant text

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines and CODE_OF_CONDUCT.md for community standards. See SECURITY.md for vulnerability reporting.

License

MIT — see LICENSE.

Available Tools

5 tools
extract_image_queryExtract Image QueryA

Transform free-form text (e.g. UI copy, context) into an optimized image search query using noun extraction.

ParametersJSON Schema
NameRequiredDescriptionDefault
contextYesFree-form text to extract search terms from

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses the core processing ('noun extraction') and output (a search query), but lacks detail on edge cases, failure modes, or the exact output format. It is not misleading but leaves room for ambiguity.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence that conveys the tool's purpose and mechanism without wasted words. It is appropriately concise and structured for quick understanding.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one parameter), the description is fairly complete. However, with no output schema, it does not specify the exact return type (e.g., whether the query is a string or object), and it does not clarify how this tool relates to sibling search tools. Still, it covers the essential transformation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already provides a description for 'context' ('Free-form text to extract search terms from'), and the tool description does not add significant new semantics beyond that. Schema coverage is 100%, so a baseline of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states a specific action ('Transform free-form text into an optimized image search query') and mechanism ('noun extraction'), distinguishing it from sibling search/attribution tools. It names the resource and the transformation clearly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context for when to use (given free-form text like UI copy or context) but does not explicitly mention alternatives or when not to use. It implies the use case without exclusions, so slightly below an explicit 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_best_imageGet Best ImageC

Return a single best image for a query.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesSearch text
orientationNoFilter by aspect ratio

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must fully disclose behavior. 'Best image' is vague—it doesn't explain how 'best' is determined, what happens when no match exists, or the output format. The description adds only the bare minimum that a single image is returned.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, making it extremely concise and front-loaded. However, it's so sparse that it omits valuable context that could be added without bloating the description, like criteria for 'best' or relationship to sibling tools.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the absence of an output schema, the description is functionally thin. It doesn't address key contextual elements like disambiguation from other search tools or behavioral edge cases, making it incomplete for a new agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers both parameters with descriptions, so baseline is 3. The tool description doesn't add any meaning beyond the schema, merely echoing the notion of a query and not mentioning orientation. Since schema coverage is 100%, no penalty, but no added value either.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Return' and identifies the resource 'best image' with a query scope, making it clear what the tool does. However, it doesn't explicitly distinguish from sibling tools like search_images, which may also return images, beyond the 'single best' phrasing.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives like search_images or search_images_batch. The description only states the mechanical function, with no context about selection criteria or expected use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

resolve_image_attributionResolve Image AttributionA

Generate provider-compliant attribution text for an image (e.g. Photo by X on Pexels).

ParametersJSON Schema
NameRequiredDescriptionDefault
urlNoImage URL (optional)
sourceYesSource (Pexels, Unsplash, etc.)
photographerYesPhotographer name

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It adds the useful context that output is 'provider-compliant' and gives an example, but it does not disclose how the optional URL is used, what happens with unsupported sources, or the exact return format beyond inference.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with a helpful parenthetical example. It conveys the essential purpose without redundant words or restating the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple and the description is mostly sufficient, but without an output schema it does not explicitly state the return type or the role of the optional URL parameter. The example implies a plain-text result, but agents may need more clarity on optional inputs.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents all parameters (100% coverage), but the description's example 'Photo by X on Pexels' adds meaningful formatting semantics, showing how photographer and source combine into the output text.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action 'Generate' and the resource 'provider-compliant attribution text for an image', with an illustrative example. This distinguishes it from sibling search/extraction tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is used after selecting an image to produce proper attribution, but it does not explicitly state when to use it versus alternatives or mention exclusions. The sibling tool names suggest different purposes (searching, extracting, getting best image), but no direct comparison is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_imagesSearch ImagesB

Search for royalty-free images from Pexels and Unsplash. Supports limit, page, and orientation filters.

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNoPage for pagination (default: 1)
limitNoMax results (default: 10)
queryYesSearch text (e.g. sunset mosque, zen yoga UI)
orientationNoFilter by aspect ratio

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose behavioral traits, but it only states that the tool searches royalty-free images and supports filters. It does not mention read-only status, authentication needs, rate limits, or return format, which are relevant for an external API search tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that states the main purpose and key filters upfront. No unnecessary filler or repetition of schema details, making it highly concise and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no output schema, so the description should explain what the search returns, but it does not explicitly mention the result type or structure. However, the schema fully documents parameters and the tool is a straightforward search, making the description minimally viable but not complete for returning data.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions already cover all four parameters with clear explanations (e.g., query, page, limit, orientation). The description adds the context of royalty-free sources but does not add any new meaning beyond what the schema provides, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: searching for royalty-free images from Pexels and Unsplash. This specific verb-resource pairing distinguishes it from sibling tools like search_images_batch, resolve_image_attribution, extract_image_query, and get_best_image.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives. It mentions supported filters but does not state when a user should choose this over search_images_batch or extract_image_query, leaving the agent to infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_images_batchSearch Images BatchA

Run multiple image searches in parallel. Returns results keyed by query.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoMax results per query (default: 5)
queriesYesList of search queries

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the transparency burden. It adds useful behavior (parallel execution, results keyed by query) but lacks information on failure handling, ordering, or performance implications. Partial but not complete transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two short sentences with the main verb and resource front-loaded. No redundant information; every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple two-parameter search tool without an output schema, the description adequately covers the core capability and return structure. It lacks error-handling details, but given low complexity and full schema coverage, it is largely complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides 100% coverage of parameter descriptions, so the baseline is 3. The description adds that results are keyed by query, hinting at the role of the `queries` parameter, but does not go beyond schema details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it runs multiple image searches in parallel, which distinguishes it from the single-search sibling tool `search_images`. It also specifies the output format (keyed by query), fully clarifying what the tool does.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is for multiple queries via 'in parallel', but it does not explicitly mention alternatives like `search_images` for single queries or state when not to use this batch version. Context is clear but no exclusions are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.2.0
    • First observedextract_image_query
    • First observedget_best_image
    • First observedresolve_image_attribution
    • First observedsearch_images
    • First observedsearch_images_batch
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0
Disambiguation3/5

search_images, get_best_image, and search_images_batch all perform image searches with slight variations, which could confuse an agent trying to pick the right one. The descriptions help clarify the differences, but the overlapping purposes create some ambiguity.

Naming Consistency4/5

Tool names generally follow a verb_noun pattern (search_images, get_best_image, resolve_image_attribution), with minor inconsistencies like search_images_batch placing the modifier at the end. Overall, the naming is readable and predictable.

Tool Count5/5

With 5 tools, the server is well-scoped for its purpose: image search and attribution. Each tool has a clear role, and the count is neither too sparse nor overwhelming.

Completeness4/5

The tool surface covers a typical workflow: optimizing a query, searching for images, picking the best one, and generating attribution. Obvious gaps are minor, such as lack of a direct image-by-URL retrieval tool, but the core functionality is solid.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ahmaddioxide/image-resolver-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server