# Unsplash-MCP图片工具
## 基本信息
- Slug: `gzpaitch-unsplash-mcp`
- Source: modelscope
- Publisher: @gzpaitch/Unsplash-MCP
- Categories: art-and-culture / search
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@gzpaitch/Unsplash-MCP
## 简介
一个以MCP工具形式提供Unsplash图片搜索、列表和随机照片功能的API，使像Claude这样的AI模型能够直接与Unsplash的服务进行交互。
## MCP Server 详情

# Unsplash API - FastAPI + FastMCP

<div align="center">
  <img src="images/UNSPLASH-MCP.png" alt="Unsplash MCP">
</div>

> Forked from [unsplash-api by @aliosmankaya](https://github.com/aliosmankaya/unsplash-api)

## 目录

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

## 概述

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

[FastAPI-MCP](https://github.com/tadata-org/fastapi_mcp)  
[FastAPI](https://github.com/fastapi/fastapi)

## 前提条件

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

1. [在 Unsplash 上注册为开发者](https://unsplash.com/developers)
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 端点

<img src="images/main-page.png" alt="API Swagger UI">

### 搜索

用于在 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 的更多信息，请参阅[官方文档](https://unsplash.com/documentation)。

## MCP 集成

### MCP 概述

Model Context Protocol (MCP) 是一种允许 AI 模型直接与 API 和服务交互的协议。此实现使用 [FastAPI-MCP](https://github.com/tadata-org/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](MCP_USAGE.md) 文件。

## 开发

要贡献开发：

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

## 许可证

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