Connect an AI assistant with MCP

With the Model Context Protocol (MCP), you can connect an AI assistant to your PixelUnion library. You can then ask things like “find photos of the beach from last summer” or “create an album called Iceland 2026 with all photos from February”, and the assistant does it for you.

This guide uses ImmichMCP, a free open-source project. It is a community project, not built or supported by PixelUnion or the Immich team. We cannot help with problems in ImmichMCP itself, but we are happy to help with the PixelUnion side.

Before you start

Please read this first. When you use a cloud AI service such as Claude or ChatGPT, the information the assistant reads from your library is sent to that service. This can include file names, dates, locations, names of people, and sometimes preview images. PixelUnion stores your photos in Europe, but once this data reaches the AI service, their privacy terms apply. If you want everything to stay on your own computer, use a local model, for example through LM Studio.

You will need:

• Your PixelUnion address (e.g. https://yourname.pixelunion.eu)
• Docker Desktop installed and running
• An AI app that supports MCP, such as Claude Desktop or LM Studio

Step 1: create an API key

1. Log in to your PixelUnion domain (e.g. https://yourname.pixelunion.eu)
2. Click your profile icon (top right) and go to Account Settings
3. Navigate to API Keys and click New API Key
4. Give it a name, for example “AI assistant”
5. Choose the permissions. We recommend starting with read-only access: asset.read, asset.view, album.read, person.read and tag.read. You can create a new key with more permissions later, for example album.create to let the assistant make albums.
6. Click Create and copy the key

You will see the key only once. Keep it somewhere safe, like a password manager.

Step 2: add ImmichMCP to Claude Desktop

1. Open Claude Desktop
2. Go to Settings → Developer and click Edit Config
3. A file called claude_desktop_config.json opens. Paste in the following, replacing the address and the key with your own:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "immich": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "IMMICH_BASE_URL=https://yourname.pixelunion.eu",
               "-e", "IMMICH_API_KEY=your-api-key",
               "ghcr.io/barryw/immichmcp:latest", "--stdio"]
    }
  }
}

4. Save the file and restart Claude Desktop completely

When Claude starts again, you will see immich in the list of connectors or tools. The first start can take a minute, because Docker downloads ImmichMCP in the background.

Other MCP apps use a similar configuration. Check your app’s documentation for where to add an MCP server.

Step 3: try it out

Start a new chat and ask something about your photos, for example:

• “How many photos do I have in PixelUnion?”
• “Find photos of a sunset at the beach”
• “Which albums do I have?”

The assistant will ask your permission before it uses a tool for the first time. Once you allow it, you will see the results in the chat.

Tips

• Deleting is protected. ImmichMCP will only delete photos or albums when the request explicitly confirms it. Even so, read what the assistant plans to do before you approve a tool call.
• Your API key is stored in plain text in the configuration file. Do not share that file, and do not use this setup on a shared computer.
• Stop access at any time by deleting the API key under Account Settings → API Keys. The assistant loses access immediately.
• Nothing happens? Check that Docker Desktop is running and that your PixelUnion address starts with https://.

We are looking at offering MCP directly from PixelUnion in the future, without Docker or API keys in a file. We have not decided yet. If you have feedback, contact us.