image-resolver

MCP 图像解析器服务

这是一个 MCP（Model Context Protocol）服务，可为 Cursor、Claude Desktop、VS Code、Windsurf 等 AI 主机提供免版税图像搜索。用自然语言让 AI 助手查找图像，它会使用 search_images 工具，并返回来自 Pexels 和 Unsplash 的结构化结果。

功能

• search_images — 搜索免版税图像（支持 limit、page、orientation）
• extract_image_query — 将自由文本转换为图像搜索查询
• get_best_image — 为查询返回最合适的单张图像
• search_images_batch — 并行执行多项搜索
• resolve_image_attribution — 生成符合提供商要求的署名文本
• Pexels & Unsplash — 支持多个提供商（两者均提供免费套餐）
• 统一响应 — 返回包含 url、source、dimensions、photographer、tags 的结构化结果
• 随处可用 — 适用于任何支持 stdio 服务的 MCP 客户端

要求

• Node.js 18+
• 至少一个 API 密钥：Pexels（pexels.com/api）和/或 Unsplash（unsplash.com/oauth/applications）

快速开始（无需安装）

无需克隆或构建。只需将此配置添加到 MCP 客户端，它便会通过 npx 自动运行：

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

必须提供至少一个 API 密钥。两者都免费，可在此获取：

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

架构（高层概览）

┌─────────────────────────────────────────────────────────────────────────────┐
│                           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                         │
└──────────────────────────────┘    └──────────────────────────────────────────┘

流程： MCP 客户端 → stdio → index.ts（注册工具）→ search-images.ts → Pexels 和 Unsplash 提供商（设置了密钥时）。结果会合并（先 Pexels，后 Unsplash），并规范化为统一的 ImageResult 架构。

客户端设置

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.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"
      }
    }
  }
}

更改配置后重启 Cursor。

Claude Desktop

添加到 Claude 配置文件：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/Claude/claude_desktop_config.json

通过设置操作：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"
      }
    }
  }
}

保存后彻底重启 Claude Desktop。

VS Code

添加到 .vscode/mcp.json（工作区级）或用户配置文件中的 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"
      }
    }
  }
}

注意： VS Code 使用 servers（而非 mcpServers），并且要求 "type": "stdio"。

Windsurf

添加到 ~/.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"
      }
    }
  }
}

更改后刷新 MCP 配置。

其他 MCP 客户端

任何支持 stdio MCP 服务的客户端（Amp、Continue.dev、Amazon Q 等）都可以使用此服务：

• 命令： npx
• 参数： ["-y", "@ahmaddioxide/mcp-image-resolver"]
• 环境变量： { "PEXELS_API_KEY": "your-key", "UNSPLASH_ACCESS_KEY": "your-key" }（至少需要一个）

用法

配置完成后，用自然语言让 AI 助手查找图像。它会自动调用 search_images 工具。

提示词示例：

• “查找日落时的清真寺免版税图像”
• “搜索适合健康应用的禅意瑜伽图像”
• “找一些极简风格的办公室工作区照片”
• “查找适合烹饪博客页眉的图像”

该工具会返回图像 URL 和元数据。使用链接查看或下载图像。

工具架构

工具	参数	描述
search_images	query, limit?, page?, orientation?	搜索 Pexels 和 Unsplash 上的图片
extract_image_query	context	从自由格式文本中提取搜索词
get_best_image	query, orientation?	返回一张最佳图片
search_images_batch	queries, limit?	并行执行多次搜索
resolve_image_attribution	photographer, source, url?	生成署名文本

**响应：**包含 results 数组的 JSON，数组元素格式为 { url, source, width, height, photographer, tags }。每个结果都包含 source（"Pexels" 或 "Unsplash"），用于署名。

**注意：**配置了两个提供方时，结果会合并，Pexels 的结果在前，Unsplash 的结果在后。使用 limit: 20 或更高的值，可在一次搜索中查看两个提供方的结果。

测试

用于验证工具的示例提示词：

• “搜索山地景观图片，limit 设为 20，并告诉我哪些结果来自 Pexels，哪些来自 Unsplash。”
• “对以下内容使用 extract_image_query：我需要一张适用于冥想应用的山景主图。”
• “对 'sunset mosque'、'pakistani flag' 和 'zen yoga' 使用 search_images_batch。”
• “为咖啡店查找一张最佳图片，并为其生成署名。”

开发

如需贡献或在本地运行，请克隆仓库并从源代码构建：

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

或者使用 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"
      }
    }
  }
}

署名

图片来源为 Pexels 和 Unsplash。根据其 API 条款：

• 显著展示指向 Pexels 和 Unsplash 的链接
• 为摄影师署名：“照片由 [姓名] 拍摄，来自 Pexels” / “照片由 [姓名] 拍摄，来自 Unsplash”
• 响应元数据包含 photographer 和 source；使用 resolve_image_attribution 生成符合要求的文本

贡献

欢迎贡献。请阅读 CONTRIBUTING.md 了解指南，并阅读 CODE_OF_CONDUCT.md 了解社区规范。有关漏洞报告，请参阅 SECURITY.md。

许可证

MIT — 请参阅 LICENSE。