Unsplash MCP server for AI agents and assistants

Securely connect your AI agents and chatbots (Claude, ChatGPT, Cursor, etc) with Unsplash MCP or direct API to search photos, find users, browse collections, and explore topics through natural language.

Unsplash logoUnsplash
Oauth2Api Key

Unsplash is a photo library with millions of high-quality images from photographers worldwide. It helps you quickly discover and use striking visuals for creative projects.

29 Tools

Try Unsplash now

Type what you want done — sign in and watch it run live in the Tool Router playground.

TOOL ROUTER PLAYGROUND
Unsplash
Try asking
TOOLS

Supported Tools

Every Unsplash action and event your agent gets out of the box.

Add Photo to Collection

Add a photo to a collection owned by the authenticated user; adding an existing member is a no-op.

Create Collection

Create a public or private collection for the authenticated Unsplash user.

Delete Collection

Permanently delete a collection owned by the authenticated Unsplash user.

Get Collection

Return full details for one Unsplash collection.

Get Current User

Return the authenticated Unsplash user's full profile and private account fields.

Get Month Stats

Return aggregate Unsplash activity statistics for the past 30 days.

Get Photo

Return full details for one Unsplash photo.

Get Photo Statistics

Return download and view statistics for one Unsplash photo.

Get Random Photo

Return one or more random Unsplash photos matching optional filters.

Get Topic

Return full details for an Unsplash topic by ID or slug.

Get Total Stats

Return all-time aggregate counts and rates for the Unsplash platform.

Get User Profile

Return an Unsplash user's complete public profile by username.

Get User Statistics

Return consolidated download and view statistics for all photos uploaded by an Unsplash user.

List Collection Photos

Return one page of photos in an Unsplash collection.

List Collections

Return one page of public Unsplash collections.

List Photos

Return one page from the Unsplash Editorial feed.

List Related Collections

Return the complete fixed array of collections related to one Unsplash collection.

List Topic Photos

Return one page of photos in an Unsplash topic.

List Topics

Return one page of Unsplash topics, optionally limited to exact topic IDs or case-preserving slugs.

List User Collections

Return one page of collections created by an Unsplash user.

List User Photos

Return one page of photos uploaded by an Unsplash user.

Remove Photo from Collection

Remove a photo from a collection owned by the authenticated Unsplash user.

Search Collections

Search public Unsplash collections and return one result page.

Search Photos

Search Unsplash photos with language, collection, safety, color, orientation, and ordering filters, returning one page at a time.

Search Users

Search public Unsplash users and return one result page.

Track Photo Download

Call this action for every download-like use of an Unsplash photo; it is mandatory and records download analytics.

Update Collection

Update the title, description, or privacy of a collection owned by the authenticated Unsplash user.

Update Current User

Update one or more profile fields for the authenticated Unsplash user; omitted fields remain unchanged.

Update Photo

Update metadata for a photo owned by the authenticated user, then return the full photo.

SETUP GUIDE

Connect Unsplash MCP Tool with your Agent

1

Install Composio

typescript
npm install @composio/core ai @ai-sdk/mcp @ai-sdk/openai
Install the Composio SDK and your agent framework
2

Create a session with MCP enabled

typescript
import { Composio } from "@composio/core";

const composio = new Composio();
const { mcp } = await composio.create("your-user-id", {
  toolkits: ["unsplash"],
  mcp: true,
});
Create a session scoped to Unsplash and read its MCP URL and headers
3

Connect your agent to the MCP server

typescript
import { createMCPClient } from "@ai-sdk/mcp";
import { openai } from "@ai-sdk/openai";
import { generateText, stepCountIs } from "ai";

const client = await createMCPClient({
  transport: { type: "http", url: mcp.url, headers: mcp.headers },
});

const { text } = await generateText({
  model: openai("gpt-5.6-sol"),
  tools: await client.tools(),
  prompt: "Search Unsplash for 10 high-resolution photos of Tokyo at night",
  stopWhen: stepCountIs(10),
});

console.log(text);
await client.close();
Pass the session's MCP URL and headers to your agent and run a Unsplash request
SETUP GUIDE

Connect Unsplash API Tool with your Agent

1

Install Composio

typescript
npm install @composio/core @composio/openai openai
Install the Composio SDK, the OpenAI provider, and the OpenAI SDK
2

Create a Composio session

typescript
import OpenAI from "openai";
import { Composio } from "@composio/core";
import { OpenAIResponsesProvider } from "@composio/openai";

const composio = new Composio({ provider: new OpenAIResponsesProvider() });
const client = new OpenAI();

const session = await composio.create("your-user-id", { toolkits: ["unsplash"] });
const tools = await session.tools();
Initialize Composio with the OpenAI Responses provider and create a session scoped to Unsplash
3

Run Unsplash tools with your agent

typescript
let response = await client.responses.create({
  model: "gpt-5.6-sol",
  tools,
  input: [{ role: "user", content: "Search Unsplash for 10 high-resolution photos of Tokyo at night" }],
});

while (response.output.some((o) => o.type === "function_call")) {
  const outputs = await composio.provider.handleToolCalls(session, response.output);
  response = await client.responses.create({
    model: "gpt-5.6-sol",
    tools,
    previous_response_id: response.id,
    input: outputs,
  });
}

console.log(response.output_text);
Send a request, execute the Unsplash tool calls through the session, and print the final answer

Why Use Composio?

AI Native Unsplash Integration

  • Supports both Unsplash MCP and direct API based integrations
  • Structured, LLM-friendly schemas for reliable photo searches and discovery
  • Rich coverage for searching photos, users, collections, topics, and statistics

Flexible Auth

  • Connect Unsplash using your own OAuth credentials or API key
  • Central place to configure, scope, and revoke Unsplash access
  • Use separate credentials for each user, project, and environment

Agent Optimized Design

  • Tools are tuned using real error and success rates to improve reliability over time
  • Clear input and output schemas help agents choose the right Unsplash operation
  • Comprehensive execution logs show what ran, when, and on whose behalf

Enterprise Grade Security

  • Fine-grained RBAC so you control which agents and users can access Unsplash
  • Scoped access to Unsplash resources with least-privilege credentials
  • Full audit trail of agent actions to support review and compliance
FRAMEWORKS

Use Unsplash with any AI Agent Framework

Choose a Framework you want to connect Unsplash with

Rolling this out across your team?

Give your team centralized access control across every framework with Composio’s MCP Gateway.

EXPLORE MCP GATEWAY
FAQ

Frequently asked questions

Start with Unsplash.It takes 30 seconds.

Managed auth, hosted MCP servers, and every Unsplash tool your agent needs.Free to start.

Start building