Unsplash 图片搜索 MCP 服务器

项目简介

本项目是一个基于 Model Context Protocol (MCP) 实现的服务器，专注于提供 Unsplash 图片搜索功能。通过集成 Unsplash API，该服务器允许 LLM 客户端（如 Cursor 编辑器）调用预设的工具来搜索 Unsplash 图库中的图片，并返回图片信息，方便用户在 LLM 应用中便捷地使用 Unsplash 的图像资源。

主要功能点

强大的图片搜索: 支持关键词搜索 Unsplash 图库。
丰富的搜索参数: 允许通过颜色、图片方向等参数进行更精确的图片筛选。
分页和排序: 支持自定义搜索结果的排序方式和每页显示的图片数量。
工具调用: 通过 MCP 协议的工具调用机制，方便 LLM 客户端集成和使用图片搜索功能。
易于集成: 提供详细的安装和配置说明，方便用户快速部署和集成到 Cursor 等 MCP 客户端。

安装步骤

克隆仓库

git clone https://github.com/hellokaton/unsplash-mcp-server.git
cd unsplash-mcp-server

创建虚拟环境 (推荐)
```
uv venv
```
安装依赖
```
uv pip install .
```
配置 Unsplash API 密钥
- 前往 Unsplash Developers Portal 注册并获取 Access Key。
- 在项目根目录下创建 '.env' 文件，并添加以下内容，将 'your_access_key_here' 替换为你的 Unsplash Access Key。
```
UNSPLASH_ACCESS_KEY=your_access_key_here
```

服务器配置

要将此 MCP 服务器集成到 MCP 客户端（例如 Cursor 编辑器），您需要配置客户端以连接到此服务器。以下是 Cursor 编辑器的 'settings.json' 配置示例：

{
  "mcpServers": {
    "unsplash": { //  服务器名称，可以自定义
      "command": "uv",  // 启动命令，这里使用 uv (需要确保 uv 命令在系统 PATH 中)
      "args": ["run", "--with", "fastmcp", "fastmcp", "run", "./server.py"], // 启动参数，指定使用 fastmcp 运行 server.py
      "env": {
        "UNSPLASH_ACCESS_KEY": "${YOUR_ACCESS_KEY}" // 环境变量，从 Cursor 的设置中读取 UNSPLASH_ACCESS_KEY
      }
    }
  }
}

注意:

请确保 'uv' 包管理器已安装并且在您的系统 PATH 环境变量中。如果不在，请将 'command' 字段设置为 'uv' 的绝对路径。
'args' 字段中的 './server.py' 是服务器脚本的相对路径。如果您的 'server.py' 文件不在工作区根目录，请修改为正确的相对或绝对路径。
'${YOUR_ACCESS_KEY}' 是 Cursor 编辑器中配置的环境变量，您需要在 Cursor 的设置中配置 'UNSPLASH_ACCESS_KEY' 变量，并填入您的 Unsplash API Access Key。这样可以避免将密钥硬编码在配置文件中。

基本使用方法

配置完成后，在支持 MCP 协议的客户端中 (如 Cursor 编辑器)，您可以使用以下 JSON 格式调用 'search_photos' 工具来搜索 Unsplash 图片：

{
  "tool": "search_photos", // 工具名称
  "query": "cat",        // 搜索关键词，例如 "cat", "mountain" 等
  "per_page": 5,        // (可选) 每页返回的图片数量，默认为 10，最大为 30
  "orientation": "landscape" // (可选) 图片方向，可选值: "landscape", "portrait", "squarish"
}

将上述 JSON 发送给 MCP 服务器，服务器将返回包含搜索结果的 JSON 响应，其中包含了图片的 ID、描述、URL 等信息。