Seamlessly interact with your Immich photo library through an AI agent using natural language and advanced metadata filtering.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install claw2immich
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install claw2immich using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is Immich Photo Library (claw2immich)?
The claw2immich skill enables AI agents to communicate directly with an Immich instance via the Model Context Protocol (MCP). It provides access to over 200 tools derived from the Immich OpenAPI spec, allowing for complex queries, person identification, and media retrieval through an automated interface. This integration is a primary example of how Openclaw Skills can bridge the gap between self-hosted data and intelligent agents.
By leveraging this skill, developers and power users can transform their photo library into a searchable, actionable database. Whether you need to find a specific person, a location, or a specific date, the claw2immich server acts as the translation layer that makes your media accessible to Large Language Models.
Immich Photo Library (claw2immich) Use Cases
- Searching for specific people across thousands of photos using facial recognition IDs and AND logic.
- Performing natural language smart searches such as finding photos of a sunset at the beach using CLIP-based indexing.
- Generating short-lived, auth-free shared links for secure photo downloads during a conversation.
- Retrieving specific asset metadata including GPS locations, capture dates, and album associations.
- Displaying optimized thumbnails directly within a chat interface using base64 encoding.
How Immich Photo Library (claw2immich) Works
- The AI agent initiates a request through the mcporter interface to the claw2immich MCP server using Openclaw Skills patterns.
- The server translates the request into a specific API call (GET or POST) against the user's Immich instance.
- Immich processes the request, such as searching the database for person IDs or generating a WebP thumbnail.
- The MCP server captures the response, ensuring it stays under the 64KB transport limit by using optimized sizes.
- The agent receives the data, such as a base64 string for an image or a JSON object containing asset metadata, to fulfill the user's prompt.
Immich Photo Library (claw2immich) Setup
First, ensure you have a running Immich instance and the claw2immich MCP server installed. Configure your MCP server in the config/mcporter.json file as follows:
{
"mcpServers": {
"immich": {
"baseUrl": "http://your-claw2immich-host:port/sse"
}
}
}
To verify the installation of this Openclaw Skills component, run the following command in your terminal:
mcporter call immich tool_access_report
Immich Photo Library (claw2immich) Data Schema & Taxonomy
The skill organizes data based on the Immich OpenAPI taxonomy. Below are the primary data entities handled:
| Entity | Key Metadata Fields |
|---|---|
| Assets | UUID, City, Country, CreatedAt (ISO 8601), isFavorite, web_url |
| People | UUID, Name, facial recognition data |
| Albums | UUID, Album Name, shared link status |
| Search Results | CLIP score, thumbnail base64 data, download URL |
All search parameters utilize specific prefixes (path_, query_, body_) to ensure strict compatibility with the underlying API endpoints.
Immich Photo Library (claw2immich) Advanced Features
- CLIP-based natural language search support for semantic image discovery.
- Multi-person filtering (AND logic) by passing an array of person IDs to the search tool.
- Configurable Access Profiles (read_only, read_write, full_scope) to limit agent permissions.
- Automatic shared link generation with 30-minute expiration for secure, temporary file access.
- Integrated base64 image delivery optimized for MCP transport constraints using the thumbnail size parameter.
SKILL.md
Loading
Related Openclaw Skills
Pixel Lobster
A transparent desktop overlay featuring a pixel art lobster that provides real-time lip-syncing for AI agent speech output.
Local-First LLM Router
A smart routing agent that prioritizes local LLMs over cloud APIs to reduce costs and enhance data privacy.
Adaptive Routing
A local-first routing engine that prioritizes privacy and cost-efficiency by intelligently escalating LLM requests to the cloud only when necessary.
Supabase
A powerful integration for querying Supabase projects and generating user analytics directly from your chat interface.
Policy Engine
A deterministic governance layer for controlling AI agent tool execution and enforcing security policies.
LanceDB Hybrid Search (Memory Plugin)
A high-performance long-term memory plugin that combines semantic vector search with keyword-based BM25 retrieval for AI agents.
Featured*
