What is Gumnut?
Gumnut is an AI-powered photo platform that turns a photo library into structured, queryable data. Every photo you upload is analyzed automatically — who is in it, what it shows, when it was taken, and where — and every one of those results is reachable through a REST API, native SDKs, a hosted MCP server, or an Immich-compatible API. Most photo products make you work inside their app. Gumnut is built the other way around: the app is one client among several, and anything you can do by hand you can also do from code or hand to an AI agent. Gumnut is a photo app in its own right — an open alternative to Google and Apple Photos that you can use directly at app.gumnut.ai or through the Immich mobile app. These docs cover the platform underneath it.What Gumnut understands about your photos
Gumnut enriches each asset as it arrives, and everything it derives is queryable:- Who — Faces are detected and grouped into people across your whole library. You can rename and merge people, and draw a face box by hand when the detector misses someone. See People and Faces.
- What — Every image is analyzed so you can search by what’s in the photo in addition to what’s in its metadata. Gumnut also generates a natural-language description of each image with vision language models to support agentic workflows.
- When — Capture time is resolved from EXIF, file metadata, and surrounding context, including timezone handling for photos that carry no UTC offset of their own.
- Where — Embedded GPS coordinates are reverse-geocoded into readable place names. Geotagged assets can be filtered by radius or map viewport, and clustered for map views.
- How — Camera, lens, and exposure settings are read from EXIF and returned alongside the asset.
Ways to build on Gumnut
Pick the surface that fits your stack, or combine them.- REST API — Full programmatic access to every Gumnut resource, with a published OpenAPI specification you can generate a client from. See the API reference tab for every endpoint.
- Native SDKs — Typed, idiomatic TypeScript and Python clients with retries, pagination, and error handling built in.
- MCP server — Connect Claude, ChatGPT, Cursor, or any MCP-compatible agent to your library over OAuth. Compatible hosts get interactive photo grids through MCP Apps, and the assistant can inspect an image’s pixels directly rather than working from metadata alone — then save an image it has edited or generated straight back into the library.
- Immich compatibility — Gumnut supplies an Immich API compatibility layer, so the Immich mobile and web apps — and tools built for Immich — work against your Gumnut library out of the box.
Who Gumnut is for
- Developers building on photos — Use Gumnut as the photo backend you’d otherwise have to build, from ingest and storage through to search.
- Teams processing photos at scale — Turn every upload into structured metadata your own systems can categorize, review, and route, across large volumes of images.
- Agent-native workflows — Give an AI assistant real access to a photo library so it can search, organize, and act on photos on your behalf.
- Anyone organizing a personal library — Search your own photos the way you remember them, by person, place, time, and what was in the frame. Back up your camera roll automatically from your phone, and connect ChatGPT or Claude to your library so it can build albums, restyle a photo, or assemble a trip into a photo book — saving any image it creates straight back into Gumnut.
No lock-in
Your photos remain yours:- An API-first architecture gives you full control over every Gumnut resource
- Open APIs let you access and export your data at any time, including the metadata Gumnut generates
- API keys can be limited to specific libraries and actions when you create them, and both keys and OAuth tokens can be revoked at any time