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の使用
# 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_IDDockerの使用
# 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で利用できます。
インタラクティブな API ドキュメントにhttp://localhost:8000/docsでアクセスします。
APIエンドポイント
検索
Unsplash で画像を検索するためのエンドポイント。
エンドポイント: /search
メソッド: GET
パラメータ:
query: 検索語（デフォルト: "nature")page: ページ番号（デフォルト: 1）per_page: 1ページあたりの写真数（デフォルト: 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: 1ページあたりの写真数（デフォルト: 10）order_by: 写真の順序 (デフォルト: "latest"、オプション: "latest"、"oldest"、"popular")
リクエスト例:
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: ランダムに写真をフィルタリングするための検索語 (デフォルト: "nature")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 ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。