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)

1. Clone the repository:

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

2. 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

3. Build and run with Docker:

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

Local Development

1. Install dependencies:

npm install

2. Create .env file (see above)

3. Run in development mode:

npm run dev

4. 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

1. Log into your Immich web interface
2. Go to Account Settings → API Keys
3. Create a new API key
4. 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:

{
  "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

1. Ensure the project is built:

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

2. Test the server works:

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

Step 2: Configure Claude Desktop

1. 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

2. Create or edit the configuration file:

If the file doesn't exist, create it with this content:

{
  "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:

{
  "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

1. Quit Claude Desktop completely
2. Relaunch Claude Desktop
3. 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:

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

   cd ~/ImmichMcpServer
   npm start

4. Check Claude Desktop logs (if available in the app)
5. 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

1. Define schemas in src/schemas/mcp-schemas.ts
2. Create tool class in src/tools/
3. 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

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

Debugging

Enable debug logging:

LOG_LEVEL=debug

Check server logs for detailed request/response information.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

MIT License - see LICENSE file for details.