Skip to main content
Gumnut provides a cloud-hosted MCP (Model Context Protocol) server that lets your AI assistant work with your photo library. You can use it from tools like Claude, Cursor, ChatGPT, and other MCP-compatible applications to search, organize, and manage your photos with natural language. In compatible MCP hosts, the assistant can also inspect image pixels directly instead of relying only on metadata or signed asset URLs.

​
What is MCP?

The Model Context Protocol is an open protocol that lets AI assistants securely interact with external systems. Gumnut’s MCP server implements this protocol, giving your assistant authenticated, rate-limited access to your Gumnut library.

​
Server URL

​
Supported Features

The MCP server exposes Gumnut’s main photo operations, including:
  • Assets: Upload, list, update, and delete photos and videos
  • Albums: Create and manage photo collections
  • Faces: Review face detections, add manual face boxes for misses, and associate faces with people
  • Libraries: Organize content across multiple libraries
  • People: Access facial recognition and people management
  • Search: Perform semantic and metadata-based searches
  • Map clustering: Group geotagged assets inside a viewport so your assistant can summarize dense areas before focusing on individual photos
  • Image understanding: Let compatible MCP hosts inspect image assets directly for tasks like reading text, describing a scene, or answering questions about visible details
If the detector misses someone, your assistant can add a manual face box, optionally attach it to a person, and come back later to review any unassigned faces.

​
MCP Apps

Gumnut supports the MCP Apps standard, enabling rich interactive UI experiences within MCP-compatible clients. When you use a client that supports MCP Apps, you’ll get visual photo grids, album cards, and other interactive elements alongside the standard tool-based interactions.

​
Let your assistant inspect photos

Gumnut’s MCP server includes a native view_asset tool for image-aware workflows. When your MCP client supports image results from tools, the assistant can look at an image asset itself rather than only its metadata or a signed asset_url meant for client rendering. This is useful when you want your assistant to:
  • Read text from signs, receipts, slides, documents, or screenshots in your library
  • Describe what is visible in a specific photo or image asset
  • Answer questions about details such as objects, colors, or layout
Your assistant will typically search or list assets first, then inspect the specific image asset it needs. If an asset is still processing or is not available as an image result yet, the tool asks the assistant to retry later instead of returning partial visual content.
MCP tool calls follow the same weighted rate-limit model as the REST API. Each tool call is charged once using the comparable REST operation, so view_asset counts like a metadata read rather than a full file download. See Rate Limiting for the cost classes and retry guidance.

​
Let your assistant save photos back

view_asset has a write-side counterpart, save_asset, which ingests a new image or video into a library from bytes the assistant supplies. Together they close the loop: your assistant can look at a photo, produce a new version of it, and save that version into your library. This is what makes prompt-driven editing work through an AI assistant rather than through a Gumnut endpoint. You can ask your assistant to restyle a photo, blur the faces of everyone under 18 before you share an album, or generate a variation on a shot, and keep the result alongside the original. A saved asset goes through the same pipeline as a normal upload — checksum deduplication, storage-cap enforcement, and the usual embedding, face-detection, and description processing — so it is searchable like anything else you upload.
save_asset takes the bytes directly and never downloads from a URL, so the assistant must have the image data itself. It is practical for images and short clips; use the REST API or an SDK to upload large videos.

​
Location-aware clustering

The MCP server also exposes get_geo_clusters for map-style browsing. Use it when you want your assistant to summarize geotagged assets inside a viewport before you ask it to focus on individual photos. Pass bbox as min_longitude,min_latitude,max_longitude,max_latitude, then choose cell_size in decimal degrees for the clustering granularity. Each cluster includes a centroid, an asset count, and a representative_asset_id you can use as a cover image or lookup key. Use get_geo_clusters when you want counts and map groupings, then switch to list_assets when you want the individual assets inside one area. For the HTTP version and its filtering behavior, see Pagination & Filtering.

​
Authentication

The MCP server supports multiple authentication methods:
  • API Keys: For CLI tools and server applications — Bearer apikey_...
  • OAuth 2.1: For browser-based tools and web applications — Bearer oat_...
  • Session Tokens: Automatic session management through cookies
See Authentication for details on each method.

​
Example Interactions

Once configured, you can interact with Gumnut through natural language in your AI assistant: Basic Operations:
Advanced Queries:
Image-Aware Prompts:
Bulk Operations:

​
Getting Started

See the MCP Setup guide for step-by-step instructions to configure the MCP server in: Those aren’t the only clients that work — any client that supports remote MCP servers and can authenticate to them, through either OAuth sign-in or a configurable Authorization header, can connect. See Any MCP client for the URL and authentication options, and Local and self-hosted models if you’re running the model on your own hardware.

​
Troubleshooting

Having issues? See the MCP Troubleshooting guide for common problems and solutions.