使用说明
Unsplash API-FastAPI+FastMCP
目录
概述
该项目提供了一个API来访问Unsplash服务，允许您搜索、列出和获取随机图像。此外，它集成了模型上下文协议（MCP），使Claude等人工智能模型能够直接与Unsplash API交互。
先决条件
在使用Unsplash API之前，您需要：
- 在Unsplash上注册为开发人员
- 获取您的访问密钥
- 将密钥配置为
UNSPLASH_CLIENT_ID在.env文件
安装
使用pip
# Clone the repository
git clone https://github.com/your-username/unsplash-api-mcp.git
cd unsplash-api-mcp
# Install dependencies
pip install -r requirements.txt
# Configure environment variables
cp .env.example .env
# Edit the .env file and add your UNSPLASH_CLIENT_ID
使用Docker
# Clone the repository
git clone https://github.com/your-username/unsplash-api-mcp.git
cd unsplash-api-mcp
# Configure environment variables
cp .env.example .env
# Edit the .env file and add your UNSPLASH_CLIENT_ID
# Build and start the container
docker compose up -d
配置
创建一个 .env 项目根目录中的文件，内容如下：
UNSPLASH_CLIENT_ID=your_access_key_here
跑步
局部的，局部的
python main.py
API将于 http://localhost:8000.
使用Docker
docker compose up -d
API将于 http://localhost:8000.
访问API交互式文档 http://localhost:8000/docs.
API终点
搜索
在Unsplash上搜索图像的端点。
端点： /search
方法： 获取
参数：
query：搜索词（默认值：“自然”）page：页码（默认值：1）per_page：每页照片数（默认值：10）order_by：照片排序（默认：“相关”，选项：“相关的”，“最新的”）
请求示例：
GET /search?query=mountains&page=1&per_page=5&order_by=latest
响应示例：
[
{
"alt_description": "mountain range under cloudy sky",
"created_at": "2023-05-15T12:34:56Z",
"username": "Photographer Name",
"image_link": "https://images.unsplash.com/photo-...",
"download_link": "https://unsplash.com/photos/...",
"likes": 123
}
...
]
照片
端点用于列出Unsplash登录页中的照片。
端点： /photos
方法： 获取
参数：
page：页码（默认值：1）per_page：每页照片数（默认值：10）order_by：照片排序（默认：“最新”，选项：“最新版”、“最旧”、“热门”）
请求示例：
GET /photos?page=1&per_page=5&order_by=popular
响应示例：
[
{
"alt_description": "scenic view of mountains during daytime",
"created_at": "2023-06-20T10:15:30Z",
"username": "Photographer Name",
"image_link": "https://images.unsplash.com/photo-...",
"download_link": "https://unsplash.com/photos/...",
"likes": 456
},
...
]
随机
从Unsplash获取随机照片的端点。
端点： /random
方法： 获取
参数：
query：用于过滤随机照片的搜索词（默认值：“自然”）count：要返回的照片数量（默认值：1，最大值：30）
请求示例：
GET /random?query=ocean&count=3
响应示例：
[
{
"alt_description": "blue ocean waves crashing on shore",
"created_at": "2023-04-10T08:45:22Z",
"username": "Photographer Name",
"image_link": "https://images.unsplash.com/photo-...",
"download_link": "https://unsplash.com/photos/...",
"likes": 789
},
...
]
有关Unsplash API的更多信息，请参阅 官方文件.
MCP集成
MCP概述
模型上下文协议（MCP）是一种允许AI模型直接与API和服务交互的协议。此实现使用 FastAPI-MCP 以将Unsplash API端点公开为MCP工具。
MCP端点
MCP服务器可在 /mcp 并将所有API端点公开为MCP工具：
- 搜索：在Unsplash上搜索图片
- 照片：从登录页面列出照片
- 随机：获取随机照片
使用AI模型
支持MCP的人工智能模型可以使用以下方式连接到此API：
http://your-server:8000/mcp
对于Claude，您可以在模型设置中或通过API配置连接。
客户端示例
您可以使用简单的Python客户端测试MCP服务器：
import requests
def test_mcp_metadata():
"""Test if the MCP server is working correctly."""
response = requests.get("http://localhost:8000/mcp/.well-known/mcp-metadata")
if response.status_code == 200:
print("MCP server working correctly!")
print(f"Response: {response.json()}")
else:
print(f"Error: {response.text}")
def list_mcp_tools():
"""List the available tools in the MCP server."""
response = requests.post(
"http://localhost:8000/mcp/jsonrpc",
json={
"jsonrpc": "2.0",
"id": 1,
"method": "mcp/list_tools"
}
)
if response.status_code == 200:
print("Available MCP tools:")
for tool in response.json()["result"]["tools"]:
print(f"- {tool['name']}: {tool['description']}")
else:
print(f"Error: {response.text}")
if __name__ == "__main__":
test_mcp_metadata()
list_mcp_tools()
有关使用MCP的更多信息，请参阅 MCP_USAGE.md 文件。
发展
为了促进发展：
- 克隆存储库
- 安装开发依赖项：
pip install -r requirements.txt - 创建一个
.env使用Unsplash API密钥文件 - 在开发模式下运行服务器：
python main.py
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。