Unsplash API - FastAPI + FastMCP
@aliosmankaya가 unsplash-api 에서 포크했습니다.
목차
Related MCP server: YouTube MCP Server
개요
이 프로젝트는 Unsplash 서비스에 접속하는 API를 제공하여 이미지를 검색, 나열, 그리고 무작위로 가져올 수 있도록 합니다. 또한, 모델 컨텍스트 프로토콜(MCP)을 통합하여 Claude와 같은 AI 모델이 Unsplash API와 직접 상호 작용할 수 있도록 합니다.
필수 조건
Unsplash API를 사용하기 전에 다음이 필요합니다.
액세스 키를 얻으세요
.env파일에서 키를UNSPLASH_CLIENT_ID로 구성합니다.
설치
pip 사용하기
지엑스피1
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 compose up -dAPI는 http://localhost:8000 에서 사용할 수 있습니다.
http://localhost:8000/docs 에서 대화형 API 설명서에 접속하세요.
API 엔드포인트
찾다
Unsplash에서 이미지를 검색하는 엔드포인트입니다.
엔드포인트: /search
방법: GET
매개변수:
query: 검색어 (기본값: "nature")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
방법: 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에서 이미지 검색
사진 : 랜딩 페이지의 사진 목록
랜덤 : 무작위 사진 가져오기
AI 모델과 함께 사용
MCP를 지원하는 AI 모델은 다음을 사용하여 이 API에 연결할 수 있습니다.
http://your-server:8000/mcpClaude의 경우 모델 설정이나 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.txtUnsplash API 키로
.env파일을 만듭니다.개발 모드에서 서버를 실행합니다:
python main.py
특허
이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여되었습니다. 자세한 내용은 라이선스 파일을 참조하세요.