简介

一个以MCP工具形式提供Unsplash图片搜索、列表和随机照片功能的API，使像Claude这样的AI模型能够直接与Unsplash的服务进行交互。

简介

一个以MCP工具形式提供Unsplash图片搜索、列表和随机照片功能的API，使像Claude这样的AI模型能够直接与Unsplash的服务进行交互。

Unsplash API - FastAPI + FastMCP

Forked from unsplash-api by @aliosmankaya

目录

• 概述
• 前提条件
• 安装
• 配置
• 运行
• API 端点
  • 搜索
  • 照片
  • 随机
• MCP 集成
  • MCP 概述
  • MCP 端点
  • 与 AI 模型一起使用
  • 示例客户端
• 开发
• 许可证

概述

该项目提供了一个访问 Unsplash 服务的 API，允许您搜索、列出和获取随机图片。此外，它还集成了 Model Context Protocol (MCP)，使像 Claude 这样的 AI 模型能够直接与 Unsplash API 交互。

FastAPI-MCP
FastAPI

前提条件

在使用 Unsplash API 之前，您需要：

1. 在 Unsplash 上注册为开发者
2. 获取您的 Access Key
3. 在 .env 文件中将该密钥配置为 UNSPLASH_CLIENT_ID

安装

使用 pip

bash

克隆仓库

git clone https://github.com/your-username/unsplash-api-mcp.git cd unsplash-api-mcp

安装依赖

pip install -r requirements.txt

配置环境变量

cp .env.example .env

编辑 .env 文件并添加您的 UNSPLASH_CLIENT_ID

使用 Docker

bash

克隆仓库

git clone https://github.com/your-username/unsplash-api-mcp.git cd unsplash-api-mcp

配置环境变量

cp .env.example .env

编辑 .env 文件并添加您的 UNSPLASH_CLIENT_ID

构建并启动容器

docker compose up -d

配置

在项目根目录下创建一个 .env 文件，并包含以下内容：

UNSPLASH_CLIENT_ID=your_access_key_here

运行

本地运行

bash python main.py

API 将在 http://localhost:8000 可用。

使用 Docker 运行

bash docker compose up -d

API 将在 http://localhost:8000 可用。

访问交互式 API 文档，请访问 http://localhost:8000/docs。

API 端点

搜索

用于在 Unsplash 上搜索图片的端点。

端点： /search

方法： GET

参数：

• query: 搜索词（默认："nature"）
• page: 页码（默认：1）
• per_page: 每页的照片数量（默认：10）
• order_by: 照片排序方式（默认："relevant"，选项："relevant", "latest"）

请求示例：

GET /search?query=mountains&page=1&per_page=5&order_by=latest

响应示例：

json [ { "alt_description": "山峦在多云天空下的景象", "created_at": "2023-05-15T12:34:56Z", "username": "摄影师姓名", "image_link": "https://images.unsplash.com/photo-...", "download_link": "https://unsplash.com/photos/...", "likes": 123 }, ... ]

照片

用于从 Unsplash 主页列出照片的端点。

端点： /photos

方法： GET

参数：

• page: 页码（默认：1）
• per_page: 每页的照片数量（默认：10）
• order_by: 照片排序方式（默认："latest"，选项："latest", "oldest", "popular"）

请求示例：

GET /photos?page=1&per_page=5&order_by=popular

响应示例：

json [ { "alt_description": "日间山景", "created_at": "2023-06-20T10:15:30Z", "username": "摄影师姓名", "image_link": "https://images.unsplash.com/photo-...", "download_link": "https://unsplash.com/photos/...", "likes": 456 }, ... ]

随机

用于从 Unsplash 获取随机照片的端点。

端点： /random方法： GET

参数：

• query: 用于筛选随机照片的搜索词 (默认: "nature")
• count: 返回的照片数量 (默认: 1, 最大: 30)

请求示例：

GET /random?query=ocean&count=3

响应示例：

json [ { "alt_description": "蓝色的海浪拍打着海岸", "created_at": "2023-04-10T08:45:22Z", "username": "摄影师姓名", "image_link": "https://images.unsplash.com/photo-...", "download_link": "https://unsplash.com/photos/...", "likes": 789 }, ... ]

有关 Unsplash API 的更多信息，请参阅官方文档。

MCP 集成

MCP 概述

Model Context Protocol (MCP) 是一种允许 AI 模型直接与 API 和服务交互的协议。此实现使用 FastAPI-MCP 将 Unsplash API 端点作为 MCP 工具暴露出来。

MCP 端点

MCP 服务器位于 /mcp，并以 MCP 工具的形式暴露所有 API 端点：

• search: 在 Unsplash 上搜索图片
• photos: 列出首页上的图片
• random: 获取随机图片

与 AI 模型配合使用

支持 MCP 的 AI 模型可以通过以下方式连接到此 API：

http://your-server:8000/mcp

对于 Claude，您可以在模型设置中或通过 API 配置连接。

示例客户端

您可以使用一个简单的 Python 客户端来测试 MCP 服务器：

python import requests

def test_mcp_metadata(): """测试 MCP 服务器是否正常工作。""" response = requests.get("http://localhost:8000/mcp/.well-known/mcp-metadata") if response.status_code == 200: print("MCP 服务器正常工作！") print(f"响应: {response.json()}") else: print(f"错误: {response.text}")

def list_mcp_tools(): """列出 MCP 服务器中的可用工具。""" response = requests.post( "http://localhost:8000/mcp/jsonrpc", json={ "jsonrpc": "2.0", "id": 1, "method": "mcp/list_tools" } ) if response.status_code == 200: print("可用的 MCP 工具:") for tool in response.json()["result"]["tools"]: print(f"- {tool['name']}: {tool['description']}") else: print(f"错误: {response.text}")

if name == "main": test_mcp_metadata() list_mcp_tools()

有关使用 MCP 的更多信息，请参阅 MCP_USAGE.md 文件。

开发

要贡献开发：

1. 克隆仓库
2. 安装开发依赖项：pip install -r requirements.txt
3. 创建一个包含您的 Unsplash API 密钥的 .env 文件
4. 以开发模式运行服务器：python main.py

许可证

本项目根据 MIT 许可证发布 - 详情请参见 LICENSE 文件。

来源

• 来源：github
• 链接：https://github.com/gzpaitch/Unsplash-MCP