How to Use the Immich (Google Photos Alternative) MCP in Windsurf

Q: How does Windsurf connect to my self-hosted Immich (Google Photos Alternative) instance?

You add the server configuration to your mcpconfig.json file with your API key and server URL. Windsurf auto-discovers the 26 tools instantly, allowing Cascade to start reading and writing to your media library.

Q: Can Cascade in Windsurf handle bulk migrations to Immich (Google Photos Alternative)?

Yes. Cascade chains uploadasset calls to push files sequentially, avoiding server lockups. It monitors the upload status of each asset and creates corresponding albums automatically.

Feed your self-hosted media library to Windsurf so Cascade can organize files, tag faces, and build albums on its own.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Immich (Google Photos Alternative) MCP to Windsurf

Create your Vinkius account to connect Immich (Google Photos Alternative) to Windsurf and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Immich (Google Photos Alternative) with Windsurf

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Automate bulk media uploads and organization

This MCP server uses `upload_asset` to send your local photos or videos directly to your self-hosted setup, while Cascade automatically groups them. You tell Cascade to upload a folder of vacation photos, and it handles the raw transmission without you running manual curl commands or clicking through a web UI. Once the files are up, the agent calls `create_album` and `update_album` to bundle them together based on the folder name or timestamps. It runs these steps back-to-back, meaning you get a fully sorted library from a single prompt in your IDE.

Manage users and access permissions

The server relies on `create_user` and `list_users` to let your agent manage who has access to your self-hosted media vaults. If a new developer or family member needs an account, you just ask Cascade to set them up directly from your workspace. The agent checks existing accounts first, creates the new profile, and returns the credentials. It handles the entire admin loop so you never have to open the browser dashboard.

Run facial recognition maintenance via MCP Server

This MCP Server uses `list_persons` and `update_person` to let Cascade clean up your facial recognition database. When the backend detects new faces, Cascade scans the list and prompts you for names to map them correctly. It updates the records in real-time. You end up with a clean, searchable index of family and friends without spending hours clicking through individual thumbnails.

Setup guide

Set up Immich (Google Photos Alternative) MCP in Windsurf

Prerequisites

Windsurf IDE installed (macOS, Windows, or Linux)
Active Vinkius subscription with a valid endpoint token

1

Open MCP configuration

Click the Cascade assistant icon in the sidebar, then click the hammer icon (🔨) at the top of the panel. Select "Configure" to open ~/.codeium/windsurf/mcp_config.json.
2

Add the Immich (Google Photos Alternative) MCP

Paste the JSON snippet shown on the right into the mcpServers object. Replace [YOUR_TOKEN_HERE] with your endpoint token from cloud.vinkius.com.
3

Refresh MCPs

Go back to the hammer icon (🔨) in Cascade and click "Refresh". Windsurf will detect the new server. No full restart is needed — the connection is hot-reloaded.
4

Verify in Cascade

Start a new Cascade conversation and ask something like "Show my Immich (Google Photos Alternative) payment history." If connected, Cascade will call the Immich (Google Photos Alternative) tools directly. You will see a green dot next to the server name in the MCP panel.

mcp_config.json

{
  "mcpServers": {
    "immich-google-photos-alternative-mcp": {
      "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
    }
  }
}

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Immich. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Immich (Google Photos Alternative) now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Immich (Google Photos Alternative) MCP in Windsurf

You add the server configuration to your `mcp_config.json` file with your API key and server URL. Windsurf auto-discovers the 26 tools instantly, allowing Cascade to start reading and writing to your media library.

Yes. Cascade chains `upload_asset` calls to push files sequentially, avoiding server lockups. It monitors the upload status of each asset and creates corresponding albums automatically.

Yes, Cascade needs access to the local image files in your workspace. It reads those files from your project directory and passes them to the `upload_asset` tool for ingestion.

Cascade reads the error response from the server, halts the chain, and tells you exactly which file failed. You can then ask it to retry or skip that specific asset.

All photo files, video files, and metadata remain on your local network or self-hosted server. The integration runs inside a secure, ephemeral V8 sandbox, meaning your actual media assets never pass through third-party servers.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript