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["Photosphere Desktop app"]
        mcp_http["MCP server (HTTP :3747/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:3747/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:3747/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:3747/mcp"
    }
  }
}

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

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

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

CLI (stdio transport)

TODO: Not sure why we have to hard code our settings to just one database!

psi mcp --db <path> 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.

1. Install psi and ensure it is on your PATH (see Installation).
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", "--db", "/absolute/path/to/your/database"]
    }
  }
}

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

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

For an encrypted database, add --key and the path to your private key PEM file:

"args": ["mcp", "--db", "/path/to/database", "--key", "/path/to/key.pem"]

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

psi mcp --db /absolute/path/to/your/database

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 --db /absolute/path/to/your/database

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 run the same get_database_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

• "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	Parameters	What it does
get_database_summary	(none)	Returns the database path, total file count, total import count, total size, database version, and root hash.
list_assets	limit (1-200, default 20), pageId (optional)	Returns a page of asset summaries sorted by photo date, newest first. Each summary includes ID, filename, content type, photo date, dimensions (width/height), location string, and GPS coordinates. Pass the returned nextPageId to fetch the next page.
get_asset_info	assetId (UUID)	Returns the full metadata record for one asset as JSON, given its UUID.
search_assets	query (substring), contentType (prefix, e.g. image or video/mp4), dateFrom / dateTo (ISO 8601), limit (1-200, default 20)	Filters assets by case-insensitive substring matched against filename and location, content-type prefix, and/or photo date range. All filters are optional. Returns asset summaries in newest-first order.
export_asset	assetId (UUID), outputPath (absolute path), type (original, display, or thumb)	Streams the requested variant of an asset to a local file. Creates parent directories as needed. Returns the output path and written file size.
add_assets	paths (array of absolute paths), dryRun (boolean, default false)	Adds files or directories to the database. With dryRun: true, scans paths and reports what would be imported without writing anything. Returns counts of files processed, added, already present, ignored, and failed, plus total size.

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.