io.github.ahmaddioxide/image-resolver
MCP server for context-aware royalty-free image search from Pexels and Unsplash
Ask AI about io.github.ahmaddioxide/image-resolver
Powered by Claude Β· Grounded in docs
I know everything about io.github.ahmaddioxide/image-resolver. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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 β
βββββββββββββββββββββββββββββββββββββββΌββββββββββββββββββββββββββββββββββββββββ
β
βββββββββββββββββββ΄ββββββββββββββββββ
βΌ βΌ
ββββββββββββββββββββββββββββββββ ββββββββββββββββββββββββββββββββββββββββββββ
β 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(notmcpServers) 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
photographerandsource; useresolve_image_attributionfor 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.
