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 the same six tools through two interchangeable transports:

flowchart LR
    subgraph client["MCP Client (Claude)"]
        cc["Claude Code / Claude Desktop"]
    end
    subgraph desktop["Photosphere Desktop"]
        electron["Electron app"]
        mcp_http["MCP server (HTTP :port/mcp)"]
        electron --> mcp_http
    end
    subgraph cli["Photosphere CLI"]
        psi["psi mcp --db <path>"]
    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:<port>/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 --db <path> starts a stdio-based MCP server. The MCP client spawns this process on demand and shuts it down when the chat session ends. 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:<port>/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:<port>/mcp"
    }
  }
}

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

{
  "mcpServers": {
    "photosphere": {
      "type": "http",
      "url": "http://localhost:<port>/mcp"
    }
  }
}

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

CLI (stdio transport)

Install psi (see Installation) so it is on your PATH. Then add the following block to your MCP client's config:

{
  "mcpServers": {
    "photosphere": {
      "command": "psi",
      "args": ["mcp", "--db", "/absolute/path/to/your/database"]
    }
  }
}

For an encrypted database, add "--key", "/absolute/path/to/key.pem" to the args array.

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

• "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

Tool	What it does
get_database_summary	Total files, total size, version, root hash for the open database.
list_assets	Page through assets sorted by photo date, newest first.
get_asset_info	Return the full metadata record for one asset by ID.
search_assets	Filter by filename / location substring, content-type prefix, and date range.
export_asset	Stream an asset's original, display, or thumbnail variant to a local file path.
add_assets	Add files or directories to the database; supports dryRun for previews.

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 --db <path> 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, double-check --db points to an existing database.
• Encrypted or S3-backed databases — currently only supported via the psi mcp --db <path> --key <path> CLI command. The embedded HTTP server supports local filesystem databases only.