Unsplash MCP Server

Unsplash MCP 服务

本项目实现了一个模型上下文协议（MCP）服务，提供与 Unsplash API 交互的工具，允许用户搜索和下载照片。

（注意：如有需要，请将 @shariqriazz 替换为正确的用户名/命名空间。）

Git 仓库： https://github.com/shariqriazz/upsplash-mcp-server （如果此 URL 不正确，请更新。）

功能

• 提供用于与 Unsplash API 交互的 MCP 工具。
• 根据搜索词、分页和方向搜索照片。
• 以指定分辨率（raw、full、regular、small）下载照片。
• 需要通过环境变量配置 Unsplash Access Key。
• 将照片下载到工作区中的本地 unsplash/ 目录。

提供的工具

• search_photos：在 Unsplash 上搜索照片。

  • 输入架构：

    {
      "type": "object",
      "properties": {
        "query": { "type": "string", "description": "The search term(s)." },
        "page": { "type": "number", "description": "Page number (default: 1).", "default": 1 },
        "per_page": { "type": "number", "description": "Items per page (default: 10, max: 30).", "default": 10, "maximum": 30 },
        "orientation": { "type": "string", "enum": ["landscape", "portrait", "squarish"], "description": "Filter by orientation." }
      },
      "required": ["query"]
    }
    

  • **输出：**返回包含搜索结果的 JSON 数据，以及包含图片链接的格式化文本摘要。

• download_photo：触发下载跟踪事件后，将 Unsplash 照片下载到工作区的 unsplash/ 文件夹。

  • 输入架构：

    {
      "type": "object",
      "properties": {
        "photo_id": { "type": "string", "description": "The ID of the photo to download." },
        "resolution": { "type": "string", "enum": ["raw", "full", "regular", "small"], "description": "Desired resolution (default: raw).", "default": "raw" },
        "filename": { "type": "string", "description": "Optional filename (e.g., my-image.jpg). Defaults to sanitized description or {photo_id}.jpg." }
      },
      "required": ["photo_id"]
    }
    

  • **输出：**返回成功消息，其中包含下载文件的路径。

（注意：此处的架构仅供参考。服务通过 MCP 暴露确切的架构。）

前置条件

• Node.js（建议 v18+）
• Bun（npm install -g bun）
• Unsplash 账户和 API Access Key（https://unsplash.com/developers）

设置与安装

1. 克隆仓库：

   git clone https://github.com/shariqriazz/upsplash-mcp-server.git # Update URL if needed
   cd upsplash-mcp-server
   

2. 安装依赖：

   bun install
   

3. 配置环境：
   • 在项目根目录中创建 .env 文件（或复制 .env.example，如果已提供）。
   • 添加你的 Unsplash Access Key：

     UNSPLASH_ACCESS_KEY="YOUR_UNSPLASH_ACCESS_KEY"
     

4. 构建服务：

   bun run build
   

   此操作会将 TypeScript 代码编译到 build/index.js。

用法（独立运行 / NPX）

独立运行（本地构建）：

你可以使用 bun 或 node 直接运行编译后的服务。请确保已在 shell 或 .env 文件中设置 UNSPLASH_ACCESS_KEY 环境变量。

# Ensure UNSPLASH_ACCESS_KEY is set
bun run build/index.js
# OR
node build/index.js

使用 NPX（如果已发布到 npm）：

如果此软件包已发布到 npm（例如，名为 unsplash-mcp-server），你可以使用 npx 直接运行。

# Ensure UNSPLASH_ACCESS_KEY is set in your environment
npx -y unsplash-mcp-server

注意：这要求该软件包已以指定名称发布到 npm。

使用 Cline 运行

1. 配置 MCP 设置： 在 Cline MCP 设置文件（例如 .roo/mcp.json 或全局设置）中添加或更新配置。主要有两种选择：

   选项 A：使用 Bun/Node（直接路径 — 推荐用于本地开发）

   此方法使用 bun（或 node）直接运行本地项目目录中已编译的脚本。

   {
     "mcpServers": {
       "unsplash-mcp-server": {
         "command": "bun", // Or "node"
         "args": [
           // Use the absolute path to the compiled index.js in your project
           "/path/to/your/upsplash-mcp-server/build/index.js"
         ],
         "env": {
           // Required: Ensure this matches your .env or is set here
           "UNSPLASH_ACCESS_KEY": "YOUR_UNSPLASH_ACCESS_KEY" // Replace with your actual key
         },
         "disabled": false,
         "alwaysAllow": [
            "search_photos",
            "download_photo"
            // "trigger_download" // Include if this tool exists and is separate
         ],
         "timeout": 3600 // Optional: Timeout in seconds (e.g., 1 hour)
       }
       // Add other servers here...
     }
   }
   

   • 重要： 将 /path/to/your/upsplash-mcp-server/build/index.js 替换为系统中的正确绝对路径。
   • 将 "YOUR_UNSPLASH_ACCESS_KEY" 替换为你的实际密钥。请从实际的 JSON 文件中移除注释。

   选项 B：使用 NPX（需要将软件包发布到 npm）

   此方法使用 npx 从 npm 注册表自动下载并运行服务软件包。如果你不想在本地克隆代码库，或更倾向于使用已发布的版本，此方法会很方便。

   {
     "mcpServers": {
       "unsplash-mcp-server": {
         "command": "npx",
         "args": [
           "-y", // Auto-confirm installation
           "unsplash-mcp-server" // Assumed npm package name - update if different
         ],
         "env": {
           // Required: Ensure this is set here or in your environment
           "UNSPLASH_ACCESS_KEY": "YOUR_UNSPLASH_ACCESS_KEY" // Replace with your actual key
         },
         "disabled": false,
         "alwaysAllow": [
            "search_photos",
            "download_photo"
         ],
         "timeout": 3600 // Optional: Timeout in seconds
       }
       // Add other servers here...
     }
   }
   

   • 确保 env 块包含所需的 UNSPLASH_ACCESS_KEY。
   • 如果已发布的 npm 软件包名称不同，请更新 args 中的 "unsplash-mcp-server"。

2. 重启/重新加载 Cline： Cline 应会检测到配置变更，并根据你选择的方法启动服务。

3. 使用工具： 现在，你可以通过 Cline 使用 search_photos 和 download_photo 工具。

开发

• 监视模式： bun run watch（通常会启动服务，并在文件变更时重新启动）
• Lint： bun run lint（检查代码风格和潜在错误）
• 格式化： bun run format（根据项目规范格式化代码）

（注意：此处假设 package.json 中包含 watch、lint、format 等标准脚本。如果你的脚本有所不同，请相应更新。）

许可证

本项目根据 MIT 许可证授权，详情请参阅 LICENSE 文件。