AI导哈

Unsplash图片搜索下载工具

一个实现Model Context Protocol (MCP)的服务，提供与Unsplash API交互的工具，允许用户搜索和下载照片。

  • by shariqriazz
  • JavaScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 shariqriazz/upsplash-mcp-server

使用说明

Unsplash MCP服务器

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

（注：更换 @shariqriazz 如果需要，请使用正确的用户名/命名空间）

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

特性

  • 提供MCP工具与Unsplash API进行交互。
  • 根据查询、分页和方向搜索照片。
  • 下载指定分辨率的照片（原始、完整、常规、小）。
  • 需要通过环境变量配置Unsplash访问密钥。
  • 将照片下载到本地 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公开确切的模式。）

先决条件

设置和安装

  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访问密钥：
      UNSPLASH_ACCESS_KEY="YOUR_UNSPLASH_ACCESS_KEY"
  4. 构建服务器：
    bun run build
    这将TypeScript代码编译为 build/index.js.

用法（独立/NPX）

独立（本地构建）：

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

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

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

如果此包发布到npm（例如，as 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.
    • 更新 "unsplash-mcp-server" 在……里面 args 如果发布的npm包名称不同。

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

  3. 使用工具： 您现在可以使用 search_photos 和 download_photo 通过Cline提供的工具。

发展

  • 观看模式： bun run watch （通常启动服务器，并在文件更改时重新启动）
  • Linting： bun run lint （检查代码的样式和潜在错误）
  • 格式： bun run format （根据项目标准格式化代码）

（注：假设标准 package.json 脚本如 watch, lint, format。如果您的脚本不同，请更新。)

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP