Claw2Immich

claw2immich is a Python MCP (Model Context Protocol) server that exposes selected Immich REST API endpoints. It uses the Immich OpenAPI spec for API metadata and surfaces a small, permission-aware tool set for common read-only checks.

- Core MCP server and capability filtering are implemented.
- Tool exposure is gated by Immich API permissions.
- Integration tests cover tool listing and permission probes.

- ping_server
- get_server_version
- tool_access_report
- write_capability_report
- get_current_user(only when permitted by API key/token)
- downloadAsset(only when API key/token is configured; returns transport-safebase64payloads and supports optionalimmich_linkdelivery mode)

All OpenAPI endpoints are exposed as tools namedimmich_<operation>orimmich_<method>_<path>. Tools are filtered based on auth presence, admin-only markers, and write capability probes (defaultPOST /api/assets).

- params:summary of required path/query/body fields
- example:short call sketch for required inputs
- returns:response schema title and key fields when available

OpenAPI tool responses for assets, albums, people, and places include aweb_urlfield with a direct link to the item in the Immich web UI (whenIMMICH_EXTERNAL_DOMAINis configured or discovered from server settings).

OpenAPI tool parameters use explicit, prefixed fields so MCP clients can discover what to set:

Legacy fieldspath_params,query_params,headers, andjson_bodyare still accepted for compatibility.

downloadAssetis intended for clients that cannot access the Immich API key directly. Default delivery mode isshared_link: the server returns a short-lived tokenized link (30 minutes) without inline payload data when supported by Immich shared-links API. For MCP JSON safety, inline payload delivery (inline_base64) remains base64-encoded. Optional compatibility modeimmich_linkreturns a direct authenticated Immich URL.

- Server instructions are sent during initialize. Use them as the short on-ramp and point to the usage guide resource.
- Initialize instructions now call out externalDomain discovery, workflow groups, do/don't guidance, and an example instruction string.
- Resource:docs://usage-guidecontains a detailed workflow guide with examples.
- Prompts: workflow templates are available under titles like "Immich: Get image", "Immich: Find person", and "Immich: Share album".

- IMMICH_BASE_URL(defaulthttp://localhost:2283)
- IMMICH_API_KEY
- IMMICH_API_TOKEN
- IMMICH_EXTERNAL_DOMAIN(optional: domain for web UI links likehttps://immich.example.com; if not set, discovered from/api/server-config)
- IMMICH_PROFILE(optional:read_only,read_write, orfull_scope)
- IMMICH_WRITE_PROBE_PATH(default/api/assets)
- IMMICH_WRITE_PROBE_METHOD(defaultPOST)
- IMMICH_DOWNLOAD_ASSET_DELIVERY(optional:shared_link(default),inline_base64, orimmich_link)

- MCP_TRANSPORT(stdio,sse, orstreamable-http; defaultstdio)
- MCP_HOST(default127.0.0.1)
- MCP_PORT(default8000)
- MCP_MOUNT_PATH(optional mount path for SSE transport)
- MCP_LOG_LEVEL(defaultINFO)

OpenAPI spec source: Version-matched spec (after/api/healthand/api/server/version):https://raw.githubusercontent.com/immich-app/immich/v{VERSION}/open-api/immich-openapi-specs.json

{ "mcpServers": { "claw2immich-readonly": { "command": "python", "args": ["c:\\path\\to\\claw2immich\\main.py"], "env": { "IMMICH_BASE_URL": "https://immich.example.com", "IMMICH_API_KEY": "your-read-only-key", "IMMICH_PROFILE": "read_only" } } } }

Use case:Full asset and album management without admin privileges.

- Allread_onlypermissions plus:
- asset.create- Upload photos/videos
- asset.update- Edit metadata, favorites
- asset.delete- Remove assets
- album.create- Create albums
- album.update- Modify albums
- album.delete- Remove albums

- All read-only tools plus:
- immich_uploadAsset,immich_updateAsset,immich_deleteAssets
- immich_createAlbum,immich_addAssetsToAlbum,immich_removeAssetFromAlbum
- immich_updateUser(own user only)
- All POST, PUT, PATCH, DELETE endpoints except admin-only

- User administration (getAllUsers,createUser,deleteUser)
- Server configuration (setServerConfig,updateServerConfig)
- System maintenance (runJobs,validateStorage)
- API key management

{ "mcpServers": { "claw2immich-readwrite": { "command": "python", "args": ["c:\\path\\to\\claw2immich\\main.py"], "env": { "IMMICH_BASE_URL": "https://immich.example.com", "IMMICH_API_KEY": "your-readwrite-key", "IMMICH_PROFILE": "read_write" } } } }

Use case:Administrative tasks, user management, server configuration.

- Allread_writepermissions plus:
- admin.user- User administration
- admin.config- Server configuration
- admin.jobs- Job management
- admin.apiKey- API key management

- All read_write tools plus:
- immich_getAllUsers,immich_createUser,immich_updateUser,immich_deleteUser
- immich_getServerConfig,immich_updateServerConfig
- immich_getAllJobs,immich_runJob
- immich_createApiKey,immich_updateApiKey,immich_deleteApiKey

{ "mcpServers": { "claw2immich-admin": { "command": "python", "args": ["c:\\path\\to\\claw2immich\\main.py"], "env": { "IMMICH_BASE_URL": "https://immich.example.com", "IMMICH_API_KEY": "your-admin-key", "IMMICH_PROFILE": "full_scope" } } } }

WhenIMMICH_PROFILEis not set, tool filtering relies solely on capability probes and the API key's actual permissions. This is backward-compatible with existing configurations.

- Useread_onlyfor AI assistants performing search and analysis without modification needs
- Useread_writefor general asset and album management workflows
- Usefull_scopeonly when administrative access is required
- Always create a dedicated Immich API key with minimal permissions for each profile

For quick local debugging without MCP client setup, use the helper script:

python helper/smart_search_cli.py --list-envs python helper/smart_search_cli.py --env .env --query "golden retriever on beach" --size 25 --order desc

- Lists available.envfiles in the current directory (.env,.env_*).
- LoadsIMMICH_BASE_URLandIMMICH_API_KEYorIMMICH_API_TOKENfrom the selected env file.
- CallsPOST /api/search/smartand prints the JSON response directly to stdout.

Integration tests use the standard libraryunittestrunner (pytest can also discover them).

Blocked tool reasons now include HTTP status or network error details to help troubleshoot capability checks.
- Ensure an Immich server is running and reachable.
- Create.env_testwith read-only credentials.
- Create.envwith full-access credentials, or setIMMICH_ENV_FULLto another file.

MCP client tests start a background server using SSE. You can override defaults:

- MCP_TEST_HOST(default127.0.0.1)
- MCP_TEST_PORT(default0for auto-assign)
- MCP_TEST_TIMEOUT(default20seconds)
- MCP_LOG_LEVEL(defaultDEBUGfor test server logs)

- IMMICH_ENV_TESTfor the restricted credentials file (default.env_test)
- IMMICH_ENV_FULLfor the full-access credentials file (default.env)

URL access integration tests (test_integration_url_access.py)

Verifies thatweb_urlfields generated by the URL decoration layer are accessible against a live Immich instance (requires session login credentials in addition to an API key).

Create.env_webin the project root (excluded by.gitignore):

IMMICH_BASE_URL=https://your-immich.example.com IMMICH_API_KEY=<api-key-with-read-access> IMMICH_EMAIL=<user@example.com> IMMICH_PASSWORD=<your-password>

IMMICH_EXTERNAL_DOMAINmay also be included to override the URL decoration base; if omitted it falls back to the/api/server-configdiscovery chain.

pytest tests/test_integration_url_access.py -v

Tests skip automatically when.env_webis absent, the server is unreachable, or the instance has no data of that type. Override the file path withIMMICH_ENV_WEB:

IMMICH_ENV_WEB=/path/to/other.env pytest tests/test_integration_url_access.py -v

Note: the container runsmain.py, which imports theclaw2immichpackage. If you change the package layout, rebuild the image so the updated package is copied into the container.

Environment variables are passed through from your shell or.envfile:

- IMMICH_BASE_URL(defaulthttp://host.docker.internal:2283)
- IMMICH_API_KEY
- IMMICH_API_TOKEN
- IMMICH_WRITE_PROBE_PATH(default/api/assets)
- IMMICH_WRITE_PROBE_METHOD(defaultPOST)

- MCP_TRANSPORT(defaultssein compose; usestreamable-httpfor HTTP)
- MCP_HOST(default0.0.0.0in compose)
- MCP_PORT(default8000; published as the host port)

Use pre-built images from GitHub Container Registry

Pre-built Docker images are automatically published to GitHub Container Registry (GHCR) for every push tomainanddevelopbranches, as well as for releases.

# Latest build from main branch docker pull ghcr.io/joeru/claw2immich:latest # Latest build from develop branch docker pull ghcr.io/joeru/claw2immich:develop # Specific version (e.g., 0.1.0) docker pull ghcr.io/joeru/claw2immich:0.1.0

docker run -e IMMICH_BASE_URL=https://immich.example.com \ -e IMMICH_API_KEY=your-api-key \ -p 8000:8000 \ ghcr.io/joeru/claw2immich:latest

docker run -e IMMICH_BASE_URL=https://immich.example.com \ -e IMMICH_API_KEY=your-api-key \ -e MCP_TRANSPORT=sse \ -e MCP_HOST=0.0.0.0 \ -p 8000:8000 \ ghcr.io/joeru/claw2immich:latest

docker run -e IMMICH_BASE_URL=https://immich.example.com \ -e IMMICH_API_KEY=your-readonly-api-key \ -e IMMICH_PROFILE=read_only \ -p 8000:8000 \ ghcr.io/joeru/claw2immich:latest

Images support multiple architectures (amd64, arm64) and are automatically selected based on your platform.

Manage your self-hosted Immich photo library through conversation — natural language search, geographic album curation, duplicate detection, and interactive HTML galleries

Publish static sites from your AI chat with one tool call — no account.

Interact with Cloudinary's media management platform using natural language.

Persistent memory for AI agents. Store and retrieve files via 14 MCP tools with OAuth 2.0 auth. Free 10GB tier.

Quickly integrate with Tencent Cloud Storage (COS) and Data Processing (CI) capabilities powered

An MCP server for controlling local audio file playback.

An MCP server for managing files and buckets on AWS S3. Requires AWS credentials for authentication.

Publish HTML, Markdown, KV, JSON, files to brewpage.app from AI assistants.

An MCP server for interacting with Dropbox files and services.

A read-only MCP server by CData that allows LLMs to query live Dropbox data. Requires the CData JDBC Driver for Dropbox.