Unsplash Mcp

Unsplash MCP 服务

一个用于从 Unsplash 获取照片并提供适当署名的 MCP（Model Context Protocol）服务。专为需要使用正确署名图片来构建内容页面的大模型设计。

功能

• 搜索照片 - 按关键词查找照片，并支持筛选（颜色、方向）
• 随机照片 - 获取随机照片，让内容更加丰富
• 下载追踪 - 符合 Unsplash API 指南
• 完整署名信息 - 每张照片都包含可直接使用的署名文本和 HTML
• 针对大模型优化 - 提供预格式化的署名字符串，方便嵌入

为什么使用此服务？

Unsplash 要求使用其照片时提供适当署名。此服务通过提供以下内容简化了操作：

• attribution_text：纯文本，例如“Photo by John Doe on Unsplash”
• attribution_html：包含适当链接的完整 HTML，可用于网页

Photo by <a href="https://unsplash.com/@johndoe">John Doe</a> on <a href="https://unsplash.com">Unsplash</a>

安装

前提条件

• Python 3.11+
• Unsplash API 访问密钥（在此获取）

快速开始

# Clone the repository
git clone https://github.com/cevatkerim/unsplash-mcp.git
cd unsplash-mcp

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install fastmcp httpx python-dotenv

# Set your API key
echo "UNSPLASH_ACCESS_KEY=your_key_here" > .env

# Run the server
fastmcp run server.py

配置

Claude Code

添加到 ~/.claude.json（用户级）或项目 .mcp.json 中：

{
  "mcpServers": {
    "unsplash": {
      "type": "stdio",
      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
      "args": ["run", "/path/to/unsplash-mcp/server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Cursor

添加到 Cursor MCP 设置中：

{
  "mcpServers": {
    "unsplash": {
      "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
      "args": ["run", "/path/to/unsplash-mcp/server.py"],
      "env": {
        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
      }
    }
  }
}

Windsurf / Cline

添加到 MCP 配置中：

{
  "unsplash": {
    "command": "/path/to/unsplash-mcp/.venv/bin/fastmcp",
    "args": ["run", "/path/to/unsplash-mcp/server.py"],
    "env": {
      "UNSPLASH_ACCESS_KEY": "your_access_key_here"
    }
  }
}

工具

search_photos

按关键词搜索照片，并可选择使用筛选条件。

参数：

参数	类型	默认值	说明
query	string	必填	搜索关键词
page	int	1	页码
per_page	int	10	每页结果数（1-30）
order_by	string	"relevant"	排序方式："relevant" 或 "latest"
color	string	null	颜色筛选（见下文）
orientation	string	null	"landscape"、"portrait"、"squarish"
content_filter	string	"low"	安全筛选："low" 或 "high"

颜色选项： black_and_white、black、white、yellow、orange、red、purple、magenta、green、teal、blue

示例：

search_photos("mountain sunset", per_page=5, orientation="landscape")

get_random_photos

获取随机照片，可选择按关键词筛选。

参数：

参数	类型	默认值	说明
query	string	null	可选的关键词筛选条件
count	int	1	照片数量（1-30）
orientation	string	null	"landscape"、"portrait"、"squarish"
content_filter	string	"low"	安全筛选："low" 或 "high"

示例：

get_random_photos(query="nature", count=3, orientation="landscape")

track_download

追踪照片下载（Unsplash API 指南要求）。

参数：

参数	类型	说明
photo_id	string	搜索结果中的照片 ID

示例：

track_download("abc123xyz")

响应格式

每张照片都包含：

{
    "id": "abc123",
    "description": "A beautiful mountain landscape",
    "alt_description": "snow-capped mountains under blue sky",
    "urls": {
        "raw": "https://images.unsplash.com/...",
        "full": "https://images.unsplash.com/...",
        "regular": "https://images.unsplash.com/...",  # Recommended for web
        "small": "https://images.unsplash.com/...",
        "thumb": "https://images.unsplash.com/..."
    },
    "width": 4000,
    "height": 3000,
    "color": "#a3c4f3",  # Dominant color for placeholders
    "blur_hash": "LKO2?U%2Tw=w...",  # For progressive loading

    # Attribution (REQUIRED when using the image)
    "photographer_name": "John Doe",
    "photographer_username": "johndoe",
    "photographer_url": "https://unsplash.com/@johndoe?utm_source=...",
    "photo_url": "https://unsplash.com/photos/abc123?utm_source=...",

    # Ready-to-use attribution
    "attribution_text": "Photo by John Doe on Unsplash",
    "attribution_html": "Photo by <a href=\"...\">John Doe</a> on <a href=\"...\">Unsplash</a>"
}

使用示例

大模型构建内容页面时：

1. 搜索相关图片：

   photos = search_photos("coffee shop interior", per_page=5)
   

2. 选择一张照片并使用：

   <img src="{photo.urls.regular}" alt="{photo.alt_description}">
   <p class="attribution">{photo.attribution_html}</p>
   

3. 如果提供下载功能，则进行追踪：

   download_url = track_download(photo.id)
   

Unsplash API 指南

此服务可帮助你遵守 Unsplash API 指南：

1. 署名 - 始终注明摄影师和 Unsplash（使用 attribution_html）
2. 热链 - 直接使用提供的 URL（可启用浏览量追踪）
3. 下载追踪 - 用户下载图片时调用 track_download()

速率限制

• 演示模式：每小时 50 次请求
• 生产环境：每小时 5,000 次请求（获批后）

许可证

MIT 许可证 - 请参阅 LICENSE 文件。

贡献

欢迎贡献！请随时提交 Pull Request。

支持

如果你觉得这个项目有用，可以考虑请我喝杯咖啡！

致谢

• 感谢 Unsplash 提供出色的免费照片 API
• 感谢 FastMCP 提供 MCP 服务框架