Grain Photo: local agent setup reference
Reference version: 2026-11-03
Human guide: https://grain.photo/guides/agents
ChatGPT: https://grain.photo/guides/chatgpt
Claude Desktop: https://grain.photo/guides/claude

PRODUCT
Grain Photo is a professional media library and AI photo/video search app for Mac.
It indexes existing folders locally and exposes catalog search through a native
MCP server and CLI. Supported workflows include finding images for a brief,
selecting portfolio images, and finding candidate footage for a script.
Indexing does not require uploading the archive. An external assistant receives
the catalog results and images the user permits; its provider policies apply.
Product overview: https://grain.photo/agents
Examples: https://grain.photo/guides/agents

PURPOSE
Connect an assistant to the user's running Grain Photo catalog on their Mac.
This reference is documentation, not permission to change a computer or catalog.
Follow the user's request and the client's permission controls.

PREREQUISITES
Grain Photo must be installed and running. The user opens Settings > Connectors
> MCP, enables Allow local tools, and chooses Copy Configuration. If the installed
build does not expose these controls, stop and identify that gap. Do not claim a
connection is working or install a development build as a workaround.

Use the copied JSON object as the source of truth for command, args, and env.
The command is the running app's native executable; args includes --mcp. Preserve
any BETTERPREVIEW_PROFILE_ROOT environment value exactly. Do not guess an app
path, substitute a different profile, or create a new writable catalog.
The native app supplies the server. No Node runtime, Python server, API key,
public tunnel, or separate filesystem MCP server is required for this connection.

CHOOSE THE CLIENT
ChatGPT desktop with local MCP support:
Settings > MCP servers > Add server > STDIO. Name it Grain Photo. Use command,
args, and any env from Grain Photo. Save and Restart. Use a local-capable session.
Official reference: https://learn.chatgpt.com/docs/extend/mcp
A hosted web-only chat cannot reach this stdio process by reading this document.
If local MCP is unavailable, explain the requirement rather than creating a
remote endpoint or pretending the local tools are connected.

Claude Desktop on the same Mac:
Claude macOS menu > Settings > Developer > Edit Config.
Configuration: ~/Library/Application Support/Claude/claude_desktop_config.json
Merge the copied object as mcpServers["grain-photo"]. Preserve every other server
and setting. Back up an existing file before writing. If grain-photo already
exists with different settings, show the difference and request confirmation.
Validate the entire file as JSON. Fully quit and reopen Claude Desktop after
the user saves their work. Keep Grain Photo running.
Official reference: https://modelcontextprotocol.io/docs/develop/connect-local-servers
This local server does not make the catalog available to Claude web or mobile.

ASSISTED SETUP
First establish whether you can edit local configuration in this session.
If yes, inspect only the relevant client configuration, propose the exact change,
and get the user's confirmation before applying it. Preserve other settings and
provide a backup path. Do not echo unrelated secrets into chat or send them to
another service. If no, format the Grain entry and walk the user through setup.
Never enable Grain's access switches on the user's behalf without their consent.
Never disable workspace security policy to make setup work.

VERIFY BEFORE SAYING CONNECTED
Discover tools and their current input schemas. Call catalog_capabilities and
catalog_list_sources with the required schema arguments. Show the actual returned
sources and permissions. No catalog writes or media reads are needed for setup.
Do not invent sample source names, counts, or successful results.
If a check fails, preserve the error and identify the failed step.

WORKFLOWS
Search: catalog_search and catalog_query; use returned filters and capabilities.
Read results: catalog_read, catalog_asset_details; respect paging and incomplete
indexing. Do not claim exhaustive results from a partial page.
Collections: catalog_collections and catalog_change_collection. Confirm the
selected asset IDs and collection action before writing.
Metadata: catalog_edit_metadata. Show proposed changes before applying them.
Media: catalog_media when explicitly permitted. Image similarity additionally
depends on preview permission and the capabilities reported by the app.
Release owned query handles with catalog_close when finished.
Tool schemas, permissions, and capabilities from the connected app take precedence
over this list. Do not invent unsupported tools or arguments.

ACCESS AND DATA
Allow local tools enables search, catalog metadata edits, and collection edits;
it is not a read-only switch. The setup check itself should be read-only.
Enable Allow tools to read previews so the assistant can inspect and compare
images. Original file bytes have a separate access control. Use previews when
original files are unnecessary. Changing media access can require reconnecting the MCP client.
Allow tools to manage existing sources is a separate permission for known sources.
Adding new paths, macOS file access, and Dropbox sign-in remain native app actions.
Catalog edits do not write original media or XMP sidecars. Grain's catalog tools
do not offer deletion of original files or arbitrary filesystem access.
Search runs locally. Tool results sent to an assistant, including catalog data and
any permitted images, are subject to that assistant provider's data handling.

CLI
Settings > Connectors > CLI > Copy Command produces a command for the actual app
and profile. The default command ends in --cli sources --json. Replace only
sources --json with tools --json to discover schemas, or help for command help.
Use the copied executable and profile; do not assume a binary named grain is on PATH.
No credentials should be embedded into a public setup link.