Unsplash API - FastAPI + FastMCP
目录
Related MCP server: YouTube MCP Server
概述
该项目提供了访问 Unsplash 服务的 API，允许您搜索、列出和获取随机图像。此外，它集成了模型上下文协议 (MCP)，使 Claude 等 AI 模型能够直接与 Unsplash API 交互。
先决条件
在使用 Unsplash API 之前，您需要：
获取您的访问密钥
在
.env文件中将密钥配置为UNSPLASH_CLIENT_ID
安装
使用 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.pyAPI 将在http://localhost:8000上可用。
使用 Docker
docker compose up -dAPI 将在http://localhost:8000上可用。
访问http://localhost:8000/docs上的交互式 API 文档。
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响应示例：
[
{
"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
方法： GET
参数：
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
方法： GET
参数：
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 上搜索图片
照片：列出着陆页上的照片
random ：获取随机照片
与 AI 模型一起使用
支持 MCP 的 AI 模型可以使用以下方式连接到此 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使用你的 Unsplash API 密钥创建一个
.env文件以开发模式运行服务器：
python main.py
执照
该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。