{
  "markdown": "# MCP Image Resolver Server\n\nAn 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.\n\n## Features\n\n- **search_images** — Search for royalty-free images (supports limit, page, orientation)\n- **extract_image_query** — Transform free-form text into an image search query\n- **get_best_image** — Return a single best image for a query\n- **search_images_batch** — Run multiple searches in parallel\n- **resolve_image_attribution** — Generate provider-compliant attribution text\n- **Pexels & Unsplash** — Multi-provider support (free tier for both)\n- **Unified response** — Structured results with url, source, dimensions, photographer, tags\n- **Works everywhere** — Any MCP client that supports stdio servers\n\n## Requirements\n\n- Node.js 18+\n- At least one API key: Pexels ([pexels.com/api](https://www.pexels.com/api/)) and/or Unsplash ([unsplash.com/oauth/applications](https://unsplash.com/oauth/applications))\n\n## Quick Start (No Installation Required)\n\nNo cloning or building needed. Just add this config to your MCP client and it runs via `npx` automatically:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nAt least one API key is required. Both are free — get them here:\n- Pexels: [pexels.com/api](https://www.pexels.com/api/)\n- Unsplash: [unsplash.com/oauth/applications](https://unsplash.com/oauth/applications)\n\n## Architecture (High-Level)\n\n```\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                           MCP Client (Cursor, Claude, VS Code, etc.)        │\n│                                     │                                       │\n│                            stdio (stdin/stdout)                             │\n└─────────────────────────────────────┼───────────────────────────────────────┘\n                                      │\n                                      ▼\n┌─────────────────────────────────────────────────────────────────────────────┐\n│                         MCP Image Resolver Server                           │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │  index.ts          MCP server entry, registers tools, stdio transport│   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                      │                                      │\n│                                      ▼                                      │\n│  ┌─────────────────────────────────────────────────────────────────────┐   │\n│  │  tools/search-images.ts   Tool handler: search_images(query)         │   │\n│  └─────────────────────────────────────────────────────────────────────┘   │\n│                                      │                                      │\n│                                      ▼                                      │\n│  ┌──────────────────────┐  ┌──────────────────────┐                        │\n│  │  providers/pexels.ts  │  │ providers/unsplash.ts │                        │\n│  │  Pexels API adapter   │  │ Unsplash API adapter  │──▶ ImageResult schema  │\n│  └──────────────────────┘  └──────────────────────┘                        │\n│               │                        │                                    │\n│               └────────────────────────┴────▶ utils/normalize.ts            │\n└─────────────────────────────────────┼───────────────────────────────────────┘\n                                      │\n                    ┌─────────────────┴─────────────────┐\n                    ▼                                   ▼\n┌──────────────────────────────┐    ┌──────────────────────────────────────────┐\n│  Pexels API                  │    │  Unsplash API                             │\n│  api.pexels.com              │    │  api.unsplash.com                         │\n└──────────────────────────────┘    └──────────────────────────────────────────┘\n```\n\n**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.\n\n## Client Setup\n\n### Cursor\n\nAdd to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nRestart Cursor after config changes.\n\n### Claude Desktop\n\nAdd to your Claude config file:\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nVia Settings: **Developer → Edit Config**\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop completely after saving.\n\n### VS Code\n\nAdd to `.vscode/mcp.json` (workspace) or your user profile `mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"image-resolver\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\n> **Note:** VS Code uses `servers` (not `mcpServers`) and requires `\"type\": \"stdio\"`.\n\n### Windsurf\n\nAdd to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@ahmaddioxide/mcp-image-resolver\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\nRefresh the MCP config after changes.\n\n### Other MCP Clients\n\nAny client that supports stdio MCP servers (Amp, Continue.dev, Amazon Q, etc.) can use this server:\n\n- **Command**: `npx`\n- **Args**: `[\"-y\", \"@ahmaddioxide/mcp-image-resolver\"]`\n- **Env**: `{ \"PEXELS_API_KEY\": \"your-key\", \"UNSPLASH_ACCESS_KEY\": \"your-key\" }` (at least one required)\n\n## Usage\n\nOnce configured, ask your AI assistant to find images in natural language. It will call the `search_images` tool automatically.\n\n**Example prompts:**\n\n- \"Find royalty-free images of a sunset mosque\"\n- \"Search for zen yoga images suitable for a wellness app\"\n- \"Get some minimalist office workspace photos\"\n- \"Find images for a cooking blog header\"\n\nThe tool returns image URLs and metadata. Use the links to view or download images.\n\n## Tool Schema\n\n| Tool                          | Params                                   | Description                              |\n|-------------------------------|------------------------------------------|------------------------------------------|\n| **search_images**             | query, limit?, page?, orientation?       | Search images from Pexels and Unsplash   |\n| **extract_image_query**       | context                                  | Extract search terms from free-form text |\n| **get_best_image**            | query, orientation?                      | Return a single best image               |\n| **search_images_batch**       | queries, limit?                          | Run multiple searches in parallel        |\n| **resolve_image_attribution** | photographer, source, url?               | Generate attribution text                |\n\n**Response:** JSON with `results` array of `{ url, source, width, height, photographer, tags }`. Each result includes `source` (`\"Pexels\"` or `\"Unsplash\"`) for attribution.\n\n**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.\n\n## Testing\n\nExample prompts to verify the tools:\n\n- *\"Search for mountain landscape with limit 20 and show me which results came from Pexels vs Unsplash.\"*\n- *\"Use extract_image_query on: I need a hero image for a meditation app with mountains.\"*\n- *\"Use search_images_batch for 'sunset mosque', 'pakistani flag', and 'zen yoga'.\"*\n- *\"Get a single best image for coffee shop and generate attribution for it.\"*\n\n## Development\n\nTo contribute or run locally, clone the repo and build from source:\n\n```bash\ngit clone https://github.com/ahmaddioxide/image-resolver-mcp.git\ncd image-resolver-mcp\nnpm install\ncp .env.example .env\n# Add PEXELS_API_KEY and/or UNSPLASH_ACCESS_KEY to .env\nnpm run build\n```\n\nOr run in development mode without building, using `tsx`:\n\n```json\n{\n  \"mcpServers\": {\n    \"image-resolver\": {\n      \"command\": \"npx\",\n      \"args\": [\"tsx\", \"/path/to/image-resolver-mcp/src/index.ts\"],\n      \"env\": {\n        \"PEXELS_API_KEY\": \"your-pexels-api-key\",\n        \"UNSPLASH_ACCESS_KEY\": \"your-unsplash-access-key\"\n      }\n    }\n  }\n}\n```\n\n## Attribution\n\nImages are sourced from [Pexels](https://www.pexels.com/) and [Unsplash](https://unsplash.com/). Per their API terms:\n\n- Provide prominent links to Pexels and Unsplash\n- Credit photographers: \"Photo by [Name] on Pexels\" / \"Photo by [Name] on Unsplash\"\n- Response metadata includes `photographer` and `source`; use `resolve_image_attribution` for compliant text\n\n## Contributing\n\nContributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community standards. See [SECURITY.md](SECURITY.md) for vulnerability reporting.\n\n## License\n\nMIT — see [LICENSE](LICENSE).",
  "bytes": 10110,
  "sha": "37876d15ae8d2119a061e75df11cad5c30150d55c8c4a2c3fc7c040acc0ca810",
  "repo_slug": "ahmaddioxide/image-resolver-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ahmaddioxide_image_resolver_350be14c/readme"
}