Skip to main content
Gumnut provides a cloud-hosted MCP (Model Context Protocol) server that enables AI assistants to interact with your photo library. This allows tools like Claude, Cursor, ChatGPT, and other MCP-compatible applications to search, organize, and manage your photos using natural language.

​
What is MCP?

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

​
Server URL

https://api.gumnut.ai/mcp

​
Supported Features

The MCP server provides access to all Gumnut API operations:
  • Assets: Upload, list, update, and delete photos/videos
  • Albums: Create and manage photo collections
  • Faces: Manage detected faces and associate them with people
  • Libraries: Organize content across multiple libraries
  • People: Access facial recognition and people management
  • Search: Perform semantic and metadata-based searches

​
MCP Apps

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

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