Immich MCP Server

An OpenAPI 3.0-based MCP (Model Context Protocol) server that provides structured access to Immich 2.0 server functionality through tools, resources, and contextual capabilities.

Features

MCP Protocol Compliance: Full implementation of MCP server interface
Immich 2.0 Integration: Authenticated access to all major Immich API endpoints
Tool-based Architecture: Each Immich endpoint group exposed as MCP tools
OpenAPI 3.0 Schema: Auto-generated discoverable schemas for all tools
Caching Layer: Optional caching for improved performance
Docker Ready: Production-ready containerization

Available Tools

Albums (`albumsTool`)

albums_list - List all albums with filtering options
albums_create - Create new albums with optional assets
albums_get - Get album details by ID
albums_update - Update album name/description
albums_delete - Delete albums
albums_add_assets - Add assets to albums
albums_remove_assets - Remove assets from albums

Assets (`assetsTool`)

assets_list - List assets with pagination and filtering
assets_get - Get asset details by ID
assets_update - Update asset properties (favorite, archived, etc.)
assets_delete - Delete assets
assets_bulk_update - Bulk update multiple assets
assets_get_statistics - Get asset statistics
assets_get_random - Get random assets

Search (`searchTool`)

search_general - General search across all entities
search_smart - AI-powered image recognition search
search_metadata - Search by EXIF metadata and location
search_explore - Explore by detected objects/faces/places

Installation

Using Docker (Recommended)

Clone the repository:

git clone https://github.com/pimpmypixel/immich-mcp-server.git
cd immich-mcp-server

Create a .env file:

IMMICH_API_KEY=your_immich_api_key_here
IMMICH_INSTANCE_URL=https://your-immich-instance.com
PORT=8000
LOG_LEVEL=info
CACHE_TTL=300

Build and run with Docker:

docker build -t immich-mcp-server .
docker run --env-file .env -p 8000:8000 immich-mcp-server

Local Development

Install dependencies:

npm install

Create .env file (see above)

Run in development mode:

npm run dev

Build for production:

npm run build
npm start

Configuration

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | IMMICH_API_KEY | Yes | - | Your Immich instance API key | | IMMICH_INSTANCE_URL | Yes | - | Base URL of your Immich instance | | PORT | No | 8000 | Port for the MCP server | | LOG_LEVEL | No | info | Logging level (error, warn, info, debug) | | CACHE_TTL | No | 300 | Cache TTL in seconds for GET requests |

Getting Immich API Key

Log into your Immich web interface
Go to Account Settings → API Keys
Create a new API key
Copy the key to your .env file

Usage with MCP Clients

Claude Desktop

You have three options for configuring Claude Desktop with the Immich MCP Server:

Option 1: Direct Node.js Execution (Recommended for Development)

{
  "mcpServers": {
    "immich": {
      "command": "node",
      "args": ["~/ImmichMcpServer/dist/index.js"],
      "env": {
        "IMMICH_API_KEY": "your_api_key",
        "IMMICH_INSTANCE_URL": "https://your-immich-instance.com"
      }
    }
  }
}

Option 2: Using npm start (Easiest)

{
  "mcpServers": {
    "immich": {
      "command": "npm",
      "args": ["start"],
      "cwd": "~/ImmichMcpServer",
      "env": {
        "IMMICH_API_KEY": "your_api_key",
        "IMMICH_INSTANCE_URL": "https://your-immich-instance.com"
      }
    }
  }
}

Option 3: Using Docker Container (Recommended for Production)

{
  "mcpServers": {
    "immich": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env", "IMMICH_API_KEY=your_api_key",
        "--env", "IMMICH_INSTANCE_URL=https://your-immich-instance.com",
        "immich-mcp-server:latest"
      ]
    }
  }
}

Or with .env file: ``json { "mcpServers": { "immich": { "command": "docker", "args": [ "run", "--rm", "-i", "--env-file", "~/ImmichMcpServer/.env", "immich-mcp-server:latest" ] } } } ``

Which Option Should You Choose?

Option 1 (Direct Node.js): Best for development, debugging, and when you want direct control
Option 2 (npm start): Easiest to set up, handles dependencies automatically
Option 3 (Docker): Best for production, isolated environment, consistent deployment

Setting Up Claude Desktop with Option 2 (Recommended)

Step 1: Prepare Your MCP Server

Ensure the project is built:

cd /Users/andreas/Herd/ImmichMcpServer
npm run build

Test the server works:

npm start
# You should see: "Immich MCP Server started successfully"
# Press Ctrl+C to stop

Step 2: Configure Claude Desktop

Find Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Create or edit the configuration file:

If the file doesn't exist, create it with this content: ``json { "mcpServers": { "immich": { "command": "npm", "args": ["start"], "cwd": "~/ImmichMcpServer", "env": { "IMMICH_API_KEY": "KEY", "IMMICH_INSTANCE_URL": "https://<URL>" } } } } ``

If the file already exists, add the immich server to the existing mcpServers object: ``json { "mcpServers": { "existing-server": { "command": "...", "args": ["..."] }, "immich": { "command": "npm", "args": ["start"], "cwd": "~/ImmichMcpServer", "env": { "IMMICH_API_KEY": "KEY", "IMMICH_INSTANCE_URL": "https://<URL>" } } } } ``

Step 3: Restart Claude Desktop

Quit Claude Desktop completely
Relaunch Claude Desktop
Verify connection: Look for MCP server indicators in Claude Desktop

Step 4: Test the Integration

In Claude Desktop, try these commands:

"List my Immich albums"
"Show me server information"
"Search for photos with 'beach'"

Troubleshooting

If Claude Desktop doesn't connect:

Check the configuration file syntax (use a JSON validator)
Verify the path: Make sure /Users/andreas/Herd/ImmichMcpServer is correct
Test manually:

   cd ~/ImmichMcpServer
   npm start

Check Claude Desktop logs (if available in the app)
Try with environment variables in .env file instead:

   {
     "mcpServers": {
       "immich": {
         "command": "npm",
         "args": ["start"],
         "cwd": "~/ImmichMcpServer"
       }
     }
   }

Other MCP Clients

Connect to the server using stdio transport on the configured port.

API Examples

List Albums

// MCP Tool Call
{
  "tool": "albums_list",
  "arguments": {
    "shared": false
  }
}

Search Assets

// Smart search for beach photos
{
  "tool": "search_smart", 
  "arguments": {
    "query": "beach sunset",
    "type": "IMAGE",
    "size": 10
  }
}

Update Asset

// Mark asset as favorite
{
  "tool": "assets_update",
  "arguments": {
    "assetId": "asset-uuid-here",
    "isFavorite": true
  }
}

Development

Project Structure

src/
├── mcp/           # MCP protocol implementation
├── immich/        # Immich API client & types
├── tools/         # Individual MCP tool definitions
├── schemas/       # Zod schemas for validation
└── utils/         # Logging, config, utilities

Adding New Tools

Define schemas in src/schemas/mcp-schemas.ts
Create tool class in src/tools/
Register in src/mcp/server.ts

Running Tests

npm test

Linting

npm run lint
npm run lint:fix

Architecture

The server acts as an intelligent middleware layer:

MCP Client → MCP Server → Immich API Proxy → Immich Instance

MCP Layer: Handles protocol compliance and tool registration
Proxy Layer: Manages authentication, caching, and error handling
Tool Layer: Converts REST operations to MCP tools with validation

Troubleshooting

Common Issues

Connection Failed: Check IMMICH_INSTANCE_URL and API key
Authentication Error: Verify API key is valid and not expired
Tools Not Available: Check logs for tool registration errors

Debugging

Enable debug logging: ``env LOG_LEVEL=debug ``

Check server logs for detailed request/response information.

Contributing

Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request

License

MIT License - see LICENSE file for details.

Immich MCP Server