Immich Photo Manager — Claude Code MCP server: features and setup
Connect an AI agent to your Immich library to search photos, sort albums, and find duplicates.
claude mcp add --env IMMICH_BASE_URL=<IMMICH_BASE_URL> --env IMMICH_API_KEY=<IMMICH_API_KEY> --env MCP_ALLOWED_HOSTS=<MCP_ALLOWED_HOSTS> --transport stdio immich-photo-manager -- uvx immich-photo-managerWhat Immich Photo Manager does
Immich Photo Manager gives an agent access to an Immich library through its API. It can search images, help organize photos, detect duplicates, and curate albums. The listing also mentions face search and PDF reports; the server includes 94 tools.
The server is for a self-hosted Immich instance and supports Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, and Zed. You need a running Immich server and an API key; without both, the agent cannot access the library. The Claude Code setup starts the server with uvx and passes the Immich address and key as environment variables.
What it helps with
- search a photo library from a prompt
- sort photos into albums
- find duplicate images
- curate photos for an album
- create a PDF photo report
Example prompts for the agent
- Find photos from my trip in Immich and collect them in an album.
- Look for duplicate photos in my Immich library.
- Create a PDF report about the photos in this album.
How to install Immich Photo Manager
Platform CLI
claude mcp add --env IMMICH_BASE_URL=<IMMICH_BASE_URL> --env IMMICH_API_KEY=<IMMICH_API_KEY> --env MCP_ALLOWED_HOSTS=<MCP_ALLOWED_HOSTS> --transport stdio immich-photo-manager -- uvx immich-photo-managerReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from immich-photo-manager <command>
Platform CLI
codex mcp add immich-photo-manager --env IMMICH_BASE_URL=<IMMICH_BASE_URL> --env IMMICH_API_KEY=<IMMICH_API_KEY> --env MCP_ALLOWED_HOSTS=<MCP_ALLOWED_HOSTS> -- uvx immich-photo-managerReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from immich-photo-manager <command>
Config file
{
"mcpServers": {
"immich-photo-manager": {
"command": "uvx",
"args": [
"immich-photo-manager"
],
"env": {
"IMMICH_BASE_URL": "<IMMICH_BASE_URL>",
"IMMICH_API_KEY": "<IMMICH_API_KEY>",
"MCP_ALLOWED_HOSTS": "<MCP_ALLOWED_HOSTS>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from immich-photo-manager <command>
Config file
{
"servers": {
"immich-photo-manager": {
"type": "stdio",
"command": "uvx",
"args": [
"immich-photo-manager"
],
"env": {
"IMMICH_BASE_URL": "<IMMICH_BASE_URL>",
"IMMICH_API_KEY": "<IMMICH_API_KEY>",
"MCP_ALLOWED_HOSTS": "<MCP_ALLOWED_HOSTS>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from immich-photo-manager <command>
Platform CLI
gemini mcp add -e IMMICH_BASE_URL=<IMMICH_BASE_URL> -e IMMICH_API_KEY=<IMMICH_API_KEY> -e MCP_ALLOWED_HOSTS=<MCP_ALLOWED_HOSTS> immich-photo-manager uvx immich-photo-managerReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from immich-photo-manager <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Immich Photo Manager
How do I install Immich Photo Manager in Claude Code?
Add the server with claude mcp add immich-photo-manager -e IMMICH_BASE_URL=<IMMICH_BASE_URL> -e IMMICH_API_KEY=<IMMICH_API_KEY> -- uvx immich-photo-manager. Provide the address of your running Immich instance and its API key.
What does Immich Photo Manager do?
It connects an AI agent to Immich for photo search, album organization, and duplicate detection. The server provides 94 tools.
What does the server need to connect?
You need a running Immich instance and an API key. The server accesses your library through the Immich API.
