无界智能MCP服务器

Name: 无界智能MCP服务器
Author: drumnation

作者：drumnation49 星标更新：2025-04-14

安装使用来源：spider==github.com

项目介绍

🖼️ Unsplash 智能 MCP 服务器

通过令人惊叹的视觉效果增强您的AI代理，无需任何麻烦。

这是一个强大的FastMCP服务器，使AI代理能够无缝地搜索、推荐并交付来自Unsplash的专业库存照片，具有智能上下文感知和自动归属管理功能。

🚀 为什么选择这个Unsplash集成

在视觉内容集成领域，我们的Unsplash智能MCP服务器作为AI驱动图像获取的权威解决方案脱颖而出：

🧠 AI代理优化：专门为像Cursor中的Claude这样的AI代理设计，通过自然语言简化图像请求。
🔍 上下文感知图像选择：智能解释模糊请求，即使从抽象提示中也能提供相关图像。
⚡ 单工具效率：通过统一的stock_photo工具处理整个图像工作流程，消除工具垃圾信息。
📊 资源优化：采用URL优先的方法，在保持灵活性的同时节省带宽和存储空间。
✅ 自动归属：内置符合Unsplash服务条款的功能，无需开发者努力。
📁 项目感知组织：根据您的项目结构（如Next.js、React、Vue等）智能组织图像。
🧩 无缝集成：设计为最小设置和最大兼容性与您现有的工作流程。

✨ 超越比较的功能

对于AI代理开发者

智能上下文搜索：通过自然语言请求找到完美的图像。
自动主题选择：AI根据您的目的描述确定最佳图像主题。
意图驱动结果：获得不仅匹配关键词，而且匹配潜在意图的图像。
无缝代理集成：开箱即用支持Cursor中的Claude和其他兼容MCP的代理。

对于项目效率

两步工作流：获取下载控制的URL，避免权限问题和不必要的存储。
项目感知文件管理：根据框架约定自动组织图像。
智能目录创建：根据您的项目类型创建适当的文件夹结构。
渐进增强：适用于任何项目规模，从快速原型到企业应用。

对于合规性的安心

完整的归属管理：
- 本地归属数据库跟踪所有图像使用情况。
- 图像中自动嵌入摄影师元数据（EXIF、IPTC、XMP）。
- 多格式一键生成归属页面。
- 全面的归属数据API。

🛠️ 安装

预备条件

Node.js 18.x或更高版本
Unsplash API访问密钥（在这里获取）

本地安装（推荐）

克隆仓库：

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

安装依赖项：

npm install

配置您的Cursor MCP设置：
- macOS：编辑~/.cursor/mcp.json
- Windows：编辑%USERPROFILE%\.cursor\mcp.json
- Linux：编辑~/.cursor/mcp.json
添加以下配置：

{
  "servers": {
    "unsplash": {
      "command": "npx",
      "args": ["tsx", "src/server.ts"],
      "cwd": "/绝对路径到/unsplash-smart-mcp-server",
      "env": {
        "UNSPLASH_ACCESS_KEY": "您的API密钥"
      }
    }
  }
}

替换：
- /绝对路径到/unsplash-smart-mcp-server为实际克隆仓库的路径
- 您的API密钥为您自己的Unsplash API密钥
保存文件并重启Cursor。

重要：与其他许多MCP服务器不同，此服务器需要直接进程管道，并且不能通过TCP端口或直接通过npm访问，因为其处理FastMCP的I/O交互方式。本地安装方法是最可靠的方法。

使用Cursor CLI的替代方案

如果您更喜欢使用Cursor的CLI：

claude mcp add unsplash npx tsx /路径到/unsplash-smart-mcp-server/src/server.ts --cwd /路径到/unsplash-smart-mcp-server
claude mcp config set unsplash UNSPLASH_ACCESS_KEY=您的API密钥

替换路径和API密钥为实际值。

通过Docker（最可靠的方法）

克隆仓库：

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

创建一个docker-compose.yml文件：

services:
  unsplash-mcp:
    build: .
    image: unsplash-mcp-server
    restart: always
    stdin_open: true
    tty: true
    environment:
      - UNSPLASH_ACCESS_KEY=您的API密钥

构建并启动容器：

docker-compose up -d

配置您的Cursor MCP设置：
- macOS：编辑~/.cursor/mcp.json
- Windows：编辑%USERPROFILE%\.cursor\mcp.json
- Linux：编辑~/.cursor/mcp.json
添加以下配置：

{
  "servers": {
    "unsplash": {
      "command": "docker",
      "args": ["exec", "-i", "unsplash-mcp-unsplash-mcp-1", "tsx", "src/server.ts"],
      "env": {}
    }
  }
}

保存文件并重启Cursor。

此设置将：

当Docker启动时自动启动服务器
如果服务器崩溃则重新启动
在后台运行而无需终端窗口
提供可靠的连接到Cursor

通过Smithery（云部署）

如果您偏好云部署，可以使用Smithery：

通过Smithery在Cursor中安装服务器：

npx @smithery/cli install @drumnation/unsplash-smart-mcp-server --client cursor --key 您的API密钥

或者，您可以登录Smithery.ai并通过他们的Web界面进行部署。

注意：对于Windows用户，Smithery部署包括特殊的Windows兼容处理。

详细的说明和故障排除，请参阅Smithery部署指南。

🧩 与AI代理的集成

步骤指南：Cursor中的Claude

我们的Unsplash智能MCP服务器旨在让通过AI代理获取图像变得轻松直观：

发起请求：只需用自然语言询问Claude要一张图片
AI解释：Claude理解您的需求，并以优化参数调用stock_photo工具
智能图像选择：服务器解释上下文并找到最相关的图像
选项展示：Claude呈现最佳匹配和下载命令
无缝下载：执行建议的命令将图像放置在您需要的位置
自动归属：所有归属数据被存储并在需要时可访问

这一过程消除了传统的流程：

~~手动搜索Unsplash~~
~~滚动数百个结果~~
~~将图像下载到随机位置~~
~~将文件移动到正确的项目文件夹~~
~~手动跟踪归属数据~~
~~创建归属页面~~

AI代理的示例提示

使用自然语言提示向Cursor中的Claude请求图像，例如：

“找到一张适合科技初创公司着陆页英雄部分的专业图片”

🪟 Windows 兼容性

如果您正在使用Windows并且在Cursor中运行MCP服务器时遇到“客户端关闭”错误，请遵循这些特殊配置步骤：

Windows特定的MCP配置

在.cursor目录中创建一个名为mcp.json的文件（通常位于%USERPROFILE%\.cursor\mcp.json），并使用以下配置之一：

选项1：直接Node执行（推荐）

{
  "mcpServers": {
    "stock_photo": {
      "command": "node",
      "args": ["./node_modules/.bin/tsx", "路径到/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        "UNSPLASH_ACCESS_KEY": "您的API密钥"
      },
      "shell": false
    }
  }
}

选项2：PowerShell方法

{
  "mcpServers": {
    "stock_photo": {
      "command": "powershell",
      "args": ["-Command", "npx tsx 路径到/unsplash-mcp/src/server.ts"],
      "disabled": false,
      "env": {
        “UNSPLASH_ACCESS_KEY”: “您的API密钥”
      }
    }
  }
}

关于Windows兼容性的完整文档，请参阅Windows兼容性指南。

🛠️ API参考

URL优先方法：明智的选择

我们的架构采用URL优先方法而不是直接嵌入图像，原因如下：

存储效率：防止AI代理在其上下文中不必要地存储大量二进制数据。
带宽节约：减少服务之间的数据传输，提高响应时间。
放置灵活性：允许开发人员将图像下载到确切需要的位置。
权限管理：避免受限环境中的文件系统权限问题。
工作流程整合：无缝整合到现有开发流水线中。

这种策略使AI代理能够基于项目上下文智能建议最优下载位置，而不受自身环境限制。

最小化工具垃圾信息和API调用

与其他需要多次工具调用来搜索、过滤、下载和归属图像的解决方案不同，我们的服务器：

统一整个图像工作流程到单一的stock_photo工具。
优化结果检索，通过提前请求更多图像来实现更好的过滤。
消除代理和服务之间的乒乓互动。
通过简化请求和响应格式减少代理令牌使用。

这种设计显著减少了API调用和工具调用的数量，从而加快了结果并降低了运营成本。

🔄 自动归属和合规性

Unsplash服务条款：轻松合规

使用Unsplash的图像需要遵守其服务条款。我们的服务器自动处理这一点：

归属数据捕获：每次图像下载都会自动存储摄影师信息。
元数据嵌入：摄影师详情直接嵌入到图像文件中。
归属数据库：本地数据库维护所有图像使用的记录。
归属生成器：内置工具创建HTML和React归属组件。
API访问：简单端点用于检索任何项目的归属数据。

通过使用我们的Unsplash智能MCP服务器，您将自动符合Unsplash的要求，无需额外努力。

归属管理系统

服务器包括一个全面的归属管理系统：

// 为您的项目检索归属数据
const attributions = await fetch('http://localhost:3000/api/unsplash', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    method: 'get_attributions',
    params: {
      format: 'json',  // 选项：json, html, react
      projectPath: '/路径到/您的项目'
    }
  })
}).then(res => res.json());

// attributions 包含每个使用图像的完整数据

API可以生成三种类型的归属文件：

JSON：用于自定义实现的结构化数据。
HTML：用于网站页脚或信用部分的现成HTML页面。
React：用于现代Web应用程序的插入式React组件。

💼 开发者工作流程集成

实际用例

我们的Unsplash智能MCP服务器无缝集成到您的开发工作流程中：

UI开发

立即填充草图与相关占位图像。
维持组件间一致的图像尺寸。
根据项目结构逻辑组织图像。

文档

增强技术文档的解释性视觉效果。
创建视觉吸引人的教程和指南。
维护所有视觉资产的适当归属。

内容创作

快速找到博客文章和文章的图像。
为社交媒体内容生成视觉效果。
访问产品营销的一致图像。

应用开发

为电子商务站点填充产品图像。
创建视觉丰富的用户体验。
为不同部分维护单独的图像集合。

框架特定的组织

图像会根据您的项目类型自动组织：

框架	默认图像路径	备选路径
Next.js	`/public/images/`	`/public/assets/images/`
React	`/src/assets/images/`	`/assets/images/`
Vue	`/src/assets/images/`	`/public/images/`
Angular	`/src/assets/images/`	`/assets/images/`
通用	`/assets/images/`	`~/Downloads/stock-photos/`

🥇 竞争差异化

为什么选择我们的Unsplash集成？

功能	Unsplash智能MCP服务器	替代方案
AI代理集成	✅ 专门针对AI代理工作流程设计	❌ 通常需要手动设置参数
上下文感知	✅ 智能解释模糊请求	❌ 依赖精确关键词匹配
工具效率	✅ 单一工具处理整个工作流程	❌ 经常需要多个独立工具
归属管理	✅ 全面系统，多种格式	❌ 手动跟踪或基本文本输出
项目组织	✅ 框架感知文件夹结构	❌ 通用下载到单个位置
安装复杂度	✅ 简单的一行命令	❌ 通常需要多个配置步骤
响应格式	✅ AI优化，带有相关上下文	❌ 通用JSON，需要进一步处理
下载灵活性	✅ URL优先，智能建议	❌ 要么直接下载，要么仅URL

⚙️ 配置

环境变量

变量	描述	默认值
`UNSPLASH_ACCESS_KEY`	您的Unsplash API访问密钥	-
`PORT`	服务器监听的端口	`3000`
`HOST`	服务器主机	`localhost`
`ATTRIBUTION_DB_PATH`	存储归属数据库的路径	`~/.unsplash-mcp`

工具参数

stock_photo

参数	类型	描述	默认值
`query`	string	搜索什么（如果未指定，AI将选择）	-
`purpose`	string	图像将用于何处（例如，英雄，背景）	-
`count`	number	返回的图像数量	`1`
`orientation`	string	偏好的方向（任意，横向，纵向，方形）	`任意`
`width`	number	目标宽度（像素）	-
`height`	number	目标高度（像素）	-
`minWidth`	number	过滤结果的最小宽度	-
`minHeight`	number	过滤结果的最小高度	-
`outputDir`	string	保存照片的目录	`~/Downloads/stock-photos`
`projectType`	string	用于文件夹结构的项目类型（next，react，vue，angular）	-
`category`	string	用于组织图像的类别（例如，英雄，背景）	-
`downloadMode`	string	是否下载图像或返回URL	`仅URL`

get_attributions

参数	类型	描述	默认值
`format`	string	输出格式（json，html，react）	`json`
`projectPath`	string	过滤特定项目路径的归属	-
`outputPath`	string	保存归属文件的位置	-

🔧 故障排除

常见问题及解决办法

问题	解决办法
连接拒绝	确保服务器正在配置的端口上运行
身份验证错误	验证您的Unsplash API密钥是否正确设置
未找到图像	尝试更广泛的搜索词或检查您的搜索查询
下载权限问题	使用`downloadMode: '仅URL'`和手动下载命令
Docker容器过早退出	确保您在Dockerfile中使用`CMD ["npm", "start"]`而不是直接运行TypeScript文件，这确保了服务器在Docker环境中持续运行。
超时错误	默认MCP超时为60秒，可能不足以下载较大的图像或处理多张图像。对于图像密集的操作：1) 每次请求处理较少的图像，2) 使用较小的图像尺寸，3) 考虑使用仅URL模式而不是自动下载，4) 检查网络连接
归属未找到	验证图像是否通过MCP服务器下载
未处理的MCP错误	如果您看到`"McpError: MCP错误-32001: 请求超时"`错误，您的请求可能花费太长时间。将其分解为较小的操作或使用仅URL的方法

🤝 贡献

欢迎贡献！请随时