API de Unsplash: FastAPI + FastMCP
Bifurcado de unsplash-api por @aliosmankaya
Tabla de contenido
Related MCP server: YouTube MCP Server
Descripción general
Este proyecto proporciona una API para acceder al servicio Unsplash, lo que permite buscar, listar y obtener imágenes aleatorias. Además, integra el Protocolo de Contexto de Modelo (MCP), lo que permite que modelos de IA como Claude interactúen directamente con la API de Unsplash.
Prerrequisitos
Antes de utilizar la API de Unsplash, debes:
Obtenga su clave de acceso
Configure la clave como
UNSPLASH_CLIENT_IDen el archivo.env
Instalación
Usando 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_IDUsando 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 -dConfiguración
Cree un archivo .env en la raíz del proyecto con el siguiente contenido:
UNSPLASH_CLIENT_ID=your_access_key_hereCorrer
En la zona
python main.pyLa API estará disponible en http://localhost:8000 .
Con Docker
docker compose up -dLa API estará disponible en http://localhost:8000 .
Acceda a la documentación interactiva de la API en http://localhost:8000/docs .
Puntos finales de API
Buscar
Punto final para buscar imágenes en Unsplash.
Punto final: /search
Método: GET
Parámetros:
query: término de búsqueda (predeterminado: "naturaleza")page: Número de página (Predeterminado: 1)per_page: Número de fotos por página (Predeterminado: 10)order_by: Orden de fotos (Predeterminado: "relevante", Opciones: "relevante", "más reciente")
Ejemplo de solicitud:
GET /search?query=mountains&page=1&per_page=5&order_by=latestEjemplo de respuesta:
[
{
"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
},
...
]Fotos
Punto final para enumerar fotos desde la página de destino de Unsplash.
Punto final: /photos
Método: GET
Parámetros:
page: Número de página (Predeterminado: 1)per_page: Número de fotos por página (Predeterminado: 10)order_by: Orden de fotos (Predeterminado: "más reciente", Opciones: "más reciente", "más antigua", "popular")
Ejemplo de solicitud:
GET /photos?page=1&per_page=5&order_by=popularEjemplo de respuesta:
[
{
"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
},
...
]Aleatorio
Punto final para obtener fotos aleatorias de Unsplash.
Punto final: /random
Método: GET
Parámetros:
query: Término de búsqueda para filtrar fotos aleatorias (Predeterminado: "naturaleza")count: Número de fotos a devolver (Predeterminado: 1, Máximo: 30)
Ejemplo de solicitud:
GET /random?query=ocean&count=3Ejemplo de respuesta:
[
{
"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
},
...
]Para obtener más información sobre la API de Unsplash, consulte la documentación oficial .
Integración MCP
Descripción general de MCP
El Protocolo de Contexto de Modelo (MCP) permite que los modelos de IA interactúen directamente con las API y los servicios. Esta implementación utiliza FastAPI-MCP para exponer los endpoints de la API de Unsplash como herramientas MCP.
Puntos finales de MCP
El servidor MCP está disponible en /mcp y expone todos los puntos finales de API como herramientas MCP:
buscar : Buscar imágenes en Unsplash
fotos : Lista de fotos de la página de destino
aleatorio : Consigue fotos aleatorias
Uso de modelos de IA
Los modelos de IA que admiten MCP pueden conectarse a esta API mediante:
http://your-server:8000/mcpPara Claude, puedes configurar la conexión en la configuración del modelo o mediante API.
Cliente de ejemplo
Puedes probar el servidor MCP con un cliente Python simple:
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()Para obtener más información sobre el uso de MCP, consulte el archivo MCP_USAGE.md .
Desarrollo
Para contribuir al desarrollo:
Clonar el repositorio
Instalar dependencias de desarrollo:
pip install -r requirements.txtCrea un archivo
.envcon tu clave API de UnsplashEjecute el servidor en modo de desarrollo:
python main.py
Licencia
Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.