Upsplash MCP Server

🚀 Unsplash 项目文档

本项目是一个实现与 Unsplash API 交互的 MCP（管理控制平面）服务器。借助该服务器，用户能够通过命令行工具便捷地搜索和下载图片。

⚠️ 重要提示

徽章链接中的用户名 "benjaming" 需要替换为实际的中文项目负责人或团队名称。同时，请将代码仓库链接中的 yourusername 替换为实际的 GitHub 账号。

🚀 快速开始

下载与安装

方法一：使用 Git 克隆仓库

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

方法二：使用 npm 安装（假设已发布到 npm）

npm install -g unsplash-mcp-server

启动服务

• 开发模式

  npm run dev
  

• 生产环境

  npm start
  

✨ 主要特性

1. 搜索图片：支持通过关键词、作者和其他筛选条件搜索 Unsplash 上的图片。
2. 分页浏览：可以按指定数量获取每一页的结果，方便处理大量数据。
3. 按方向筛选：用户可以选择垂直或水平方向的图片进行搜索。
4. 下载功能：支持下载不同分辨率（如小、中、大）的图片。
5. 环境配置：通过环境变量 UNSPLASH_ACCESS_KEY 配置访问密钥，便于身份验证。

📦 安装指南

下载与安装

方法一：使用 Git 克隆仓库

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

方法二：使用 npm 安装（假设已发布到 npm）

npm install -g unsplash-mcp-server

启动服务

• 开发模式

  npm run dev
  

• 生产环境

  npm start
  

💻 使用示例

基础用法

搜索图片 (search_photos)

cline search_photos --query "nature" --per_page 10 --orientation landscape

输入参数：

• --query：必填，搜索关键词。
• --page：可选，默认为第一页。
• --per_page：每页结果数量，默认为 20。
• --orientation：可选，筛选图片方向（portrait 或 landscape）。

输出结果：返回 JSON 格式的搜索结果列表，包含图片 ID、URL 等信息。

下载图片 (download_photo)

cline download_photo --photo_id abc123 --size large

输入参数：

• --photo_id：必填，目标图片的唯一标识符。
• --size：可选，默认为中等分辨率。

📚 详细文档

代码仓库

• GitHub 仓库：Unsplash API MCP 服务（请将 yourusername 替换为实际的 GitHub 账号）

工具使用说明

搜索图片 (search_photos)

示例命令：

cline search_photos --query "nature" --per_page 10 --orientation landscape

输入参数：

• --query：必填，搜索关键词。
• --page：可选，默认为第一页。
• --per_page：每页结果数量，默认为 20。
• --orientation：可选，筛选图片方向（portrait 或 landscape）。

输出结果：返回 JSON 格式的搜索结果列表，包含图片 ID、URL 等信息。

下载图片 (download_photo)

示例命令：

cline download_photo --photo_id abc123 --size large

输入参数：

• --photo_id：必填，目标图片的唯一标识符。
• --size：可选，默认为中等分辨率。

环境配置

创建或修改 .env 文件，添加以下内容：

UNSPLASH_ACCESS_KEY=your_actual_key_here

使用 Cline 配置 MCP 服务

在项目的 .roo/mcp.json 文件中添加以下配置：

{
  "mcpServers": {
    "unsplash-mcp-server": {
      "command": "bun",
      "args": [
        "/path/to/your/unsplash-mcp-server/build/index.js"
      ],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_actual_key_here"
      }
    }
  }
}

开发指南

运行脚本

• 开发模式

  npm run dev
  

• 生产构建

  npm run build
  

监控与调试

使用 npm run watch 命令实时监控代码变化，并通过 npm run lint 进行代码检查。

📄 许可证

本项目遵循 MIT 许可证，具体内容请参考 LICENSE 文件。