Immich MCP Server

KR: Immich REST API를 MCP(Model Context Protocol) 도구로 제공하는 서버입니다. Immich의 서버 정보, 앨범, 자산, 사람, 태그 작업을 자연어 워크플로우로 연결할 수 있습니다.
EN: This server exposes Immich REST APIs as MCP (Model Context Protocol) tools. It connects Immich server info, albums, assets, people, and tag workflows to natural-language clients.

KR: stdio와 Streamable HTTP 전송을 모두 지원하며, mcp-mattermost와 비슷한 단순한 구조로 구현했습니다.
EN: It supports both stdio and Streamable HTTP transport and follows a simple structure similar to mcp-mattermost.

Environment

IMMICH_URL=https://your-immich.example.com
IMMICH_API_KEY=your-api-key
PORT=3000
TRANSPORT=stdio
IMMICH_TIMEOUT_MS=30000

• KR: IMMICH_URL은 Immich 서버의 루트 주소를 넣으세요. 코드가 /api를 자동으로 붙입니다.
• EN: Set IMMICH_URL to the Immich server root. The client automatically appends /api.
• KR: IMMICH_API_KEY는 Immich API Keys에서 발급한 키를 사용합니다.
• EN: IMMICH_API_KEY should be an API key created in Immich.
• KR: IMMICH_TOKEN도 호환 별칭으로 사용할 수 있습니다.
• EN: IMMICH_TOKEN is accepted as a compatibility alias.

Install

npm install
npm run build

Run

Stdio

npm start

Streamable HTTP

npm run start:http

MCP Configuration

Stdio

{
  "mcpServers": {
    "immich": {
      "command": "npx",
      "args": ["-y", "mcp-immich"],
      "env": {
        "IMMICH_URL": "https://your-immich.example.com",
        "IMMICH_API_KEY": "YOUR_API_KEY",
        "TRANSPORT": "stdio"
      }
    }
  }
}

HTTP / SSE

{
  "mcpServers": {
    "immich": {
      "type": "streamable-http",
      "url": "http://<server-ip>:3000/mcp"
    }
  }
}

Legacy SSE

{
  "mcpServers": {
    "immich": {
      "type": "sse",
      "url": "http://<server-ip>:3000/sse"
    }
  }
}

Tools

Server

• immich_get_server_info
• immich_get_server_statistics
• immich_get_current_user
• immich_list_jobs
• immich_request

Albums

• immich_list_albums
• immich_get_album
• immich_create_album
• immich_update_album
• immich_delete_album
• immich_add_assets_to_album
• immich_remove_assets_from_album
• immich_add_users_to_album
• immich_remove_user_from_album
• immich_update_album_user_role

Assets and People

• immich_get_asset
• immich_get_asset_metadata
• immich_update_asset
• immich_update_asset_metadata
• immich_search_assets
• immich_list_people
• immich_search_people

Tags

• immich_list_tags
• immich_create_tag
• immich_tag_assets
• immich_bulk_tag_assets

Notes

• KR: 정확한 endpoint payload가 필요한 경우 immich_request로 직접 호출할 수 있습니다.
• EN: If you need an exact endpoint payload, use immich_request to call the API directly.
• KR: 이 서버는 Immich API 문서의 /auth, /albums, /assets, /people, /search, /server, /tags, /jobs 계열 엔드포인트를 기준으로 구성했습니다.
• EN: This server is based on Immich API documentation for /auth, /albums, /assets, /people, /search, /server, /tags, and /jobs endpoints.