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

https://api.gumnut.ai/mcp

​
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
  • 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.

​
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: 
"List all my photo albums"
"Upload this image to my library"
"Create a new album called 'Summer 2024'"
"Find all photos taken in December"
Advanced Queries: 
"Show me photos with detected faces"
"Find all images similar to this one"
"Get photos taken with an iPhone 15 Pro"
"List assets that haven't been processed yet"
Image-Aware Prompts: 
"Find the photo of the whiteboard from this week and summarize what's written on it"
"Read the text on the menu photo from last night"
"Look at my latest receipt photo and tell me the total amount"
Bulk Operations: 
"Add all beach photos to a new album"
"Delete all duplicate images"
"Organize photos by date into monthly albums"
"Tag all photos with detected people"

​
Getting Started

See the MCP Setup guide for step-by-step instructions to configure the MCP server in:

​
Troubleshooting

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