Claude Integration

Claude Integration

Photosphere ships with a built-in MCP (Model Context Protocol) server so that Claude-compatible clients (Claude Desktop, Claude Code, and others) can read and write your media database directly. Once connected, Claude can answer questions about your photos and videos, search them, export files, and import new ones, all without leaving the chat.

How it works

Photosphere exposes its MCP tools through two interchangeable transports. The desktop server exposes the same tools as the CLI, plus a few additional ones for modifying media files.

flowchart LR
    subgraph client["MCP Client (Claude)"]
        cc["Claude Code / Claude Desktop"]
    end
    subgraph desktop["Photosphere Desktop"]
        electron["Photosphere Desktop app"]
        mcp_http["MCP server (HTTP :3475/mcp)"]
        electron --> mcp_http
    end
    subgraph cli["Photosphere CLI"]
        psi["psi mcp"]
    end
    db[("Media database")]
    cc -->|"HTTP"| mcp_http
    cc -->|"stdio"| psi
    mcp_http --> db
    psi --> db

Loading

• HTTP transport (desktop app): the Photosphere desktop app hosts an embedded HTTP MCP server bound to http://localhost:3475/mcp. It is always wired to whichever database is currently open in the app. Closing the database in the GUI immediately disables every tool until a database is reopened.
• stdio transport (CLI): running psi mcp starts a stdio-based MCP server. The MCP client spawns this process on demand and shuts it down when the chat session ends. The CLI server starts with no database open; Claude picks one at runtime using the list_databases and open_database tools. Use this when the desktop app is not running, when you want Claude to operate against a different database, or in headless / server environments.

Integration instructions

Desktop app (HTTP transport)

1. Launch the Photosphere desktop app and open the database you want Claude to access.
2. Open the About page in the app. The MCP address (http://localhost:3475/mcp) is displayed with a "Copy" button.
3. Paste the address into your client's MCP config.

Claude Code: .claude/settings.json (project) or ~/.claude/settings.json (user):

{
  "mcpServers": {
    "photosphere": {
      "type": "http",
      "url": "http://localhost:3475/mcp"
    }
  }
}

Claude Desktop: edit claude_desktop_config.json from the app's developer settings:

{
  "mcpServers": {
    "photosphere": {
      "type": "http",
      "url": "http://localhost:3475/mcp"
    }
  }
}

Reload the client and you should see photosphere listed as a connected MCP server.

CLI (stdio transport)

psi mcp starts a stdio-based MCP server. The MCP client (Claude Code or Claude Desktop) spawns and manages this process automatically based on your config; you do not need to start it manually. The process lives only for the duration of the chat session.

The CLI server does not take a --db flag. It starts with no database open, and Claude selects a database at runtime by calling list_databases (which lists the databases registered in databases.toml) and then open_database by name or path. To make a database available, register it first with psi dbs add (see Managing-Databases).

1. Install psi and ensure it is on your PATH (see Installation-CLI).
2. Add the following config to your MCP client.
3. Reload the client. You should see photosphere listed as a connected MCP server.

Claude Code: .claude/settings.json (project) or ~/.claude/settings.json (user):

{
  "mcpServers": {
    "photosphere": {
      "command": "psi",
      "args": ["mcp"]
    }
  }
}

Claude Desktop: edit claude_desktop_config.json from the app's developer settings:

{
  "mcpServers": {
    "photosphere": {
      "command": "psi",
      "args": ["mcp"]
    }
  }
}

Encrypted or S3-backed databases: register the database with psi dbs add and link its encryption key and/or S3 credentials (see Managing-Secrets). When Claude opens that database by name with open_database, the linked credentials are resolved automatically from the vault, no key path is passed to the MCP server.

To verify the command works before connecting a client, run it directly in a terminal:

psi mcp

It prints Photosphere MCP server running to stderr, then waits for JSON-RPC input on stdin. Press Ctrl-C to exit.

Testing your connection

HTTP transport (desktop app)

1. Launch the Photosphere desktop app and open a database.
2. Start a new Claude Code session (so it picks up the MCP config).
3. Run this prompt to confirm the server is reachable and the database is open:

Summarise my Photosphere database.

A working connection returns the database path, total asset count, and version. If Claude reports a connection error, check that the desktop app is running. If it reports "No database is currently open", open a database in the app and try again.

stdio transport (CLI)

Verify the command works before connecting a client:

psi mcp

It prints Photosphere MCP server running to stderr, then waits for JSON-RPC input on stdin. Press Ctrl-C to exit. Once confirmed, start a Claude Code session and ask it to list your databases and open one, then run the summary prompt above.

What you can do

Once connected, you can talk to your database in plain English. Here are some prompts grouped by category.

Exploring your library

• "List my Photosphere databases and open the main one."
• "How many photos and videos are in my database?"
• "List my 10 most recent photos."
• "What photos do I have from 2022?"

Searching

• "Find all photos taken in Paris."
• "Show me videos from my holiday."
• "Find photos taken in January 2023."

Getting details

• "Tell me everything about asset <id>."
• "What are the GPS coordinates of this photo?"

Exporting

• "Export the original of asset <id> to ~/Downloads/photo.jpg."
• "Save the thumbnail of asset <id> to /tmp/thumb.jpg."

Adding files

• "Add all the photos in ~/Pictures/Holiday to my Photosphere database."
• "Do a dry run of adding ~/Desktop/new-photos so I can see what would be imported."

Tool reference

The CLI MCP server registers these tools:

Tool	Parameters	What it does
list_databases	(none)	Lists the databases configured in this installation (from databases.toml).
open_database	path (database name or path)	Opens a database by name (from list_databases) or by path. Becomes the active database for subsequent tools.
close_database	(none)	Closes the currently open database (does not unregister it from databases.toml).
get_database_summary	(none)	Returns a summary of the open database (file count, total size, hashes).
list_media_files	limit (1-200, default 20), pageId (optional)	Returns a page of media files sorted by photo date, newest first. Pass the returned page ID to fetch the next page.
get_media_file_info	assetId	Returns the full metadata record for a single media file.
search_media_files	query (substring, optional), contentType (prefix, e.g. image or video/mp4), dateFrom / dateTo (ISO 8601), limit (1-200, default 20)	Searches photos and videos by filename, location, content-type prefix, and/or photo date range. All filters optional. Returns summaries newest-first.
save_media_file	assetId, outputPath, type (original, display, or thumb; default original)	Saves the requested variant of a media file to a path on disk.
import_media_files	paths (array of paths), dryRun (boolean, default false)	Imports photos and videos from files or directories. With dryRun: true, reports what would be imported without writing.
verify_database	(none)	Runs a full integrity check over the open database and returns a summary of any issues.

The desktop (HTTP) server registers the same tools plus a few additional ones for opening, deleting, and updating media files (open_media_file, delete_media_file, update_media_file).

Troubleshooting

• photosphere shows as "failed to connect" in Claude Code: confirm the address (HTTP) or psi install (stdio) is correct. For HTTP, check that the desktop app is running. For stdio, run psi mcp manually and verify it prints "Photosphere MCP server running" to stderr.
• All tools return "No database is currently open": for HTTP, open a database in the desktop app. For stdio, ask Claude to call list_databases and then open_database to select one (register it first with psi dbs add if it is not listed).
• Encrypted or S3-backed databases: register the database with psi dbs add and link its encryption key / S3 credentials, then open it by name with open_database so credentials resolve automatically from the vault.