Try Picsha from Claude

This is a hands-on walkthrough of the Picsha connector for Claude. In about ten minutes you will create a Picsha account from inside Claude, add three photos, and have Claude find, show, tag, crop and tidy them, using only chat.

You need a Claude account with access to custom connectors (Claude Desktop or claude.ai) and an email address for the new Picsha account. You do not need an API key. Claude signs in to Picsha with OAuth, the same way it connects to Google Drive or GitHub.

If you would rather drive it from Claude Code with an API key, skip to Part 2.

The sample photos

The walkthrough uses three public photos so that every step has a known right answer. Copy the three URLs; you will paste them into Claude in step 2.

Any public image URL works the same way. These three are just convenient because you know what is in them.

Part 1: Claude Desktop or claude.ai

Step 1: Connect Claude to Picsha

1. In Claude, open Settings → Connectors and choose Add custom connector.
2. Enter https://api.picsha.ai/v1/mcp as the URL and save.
3. Click Connect. Claude opens the Picsha sign-in page in your browser.
4. Choose Sign up, create your account with your email, and approve the connection when asked.

You land back in Claude. Start a new chat and confirm the Picsha connector is enabled for it (the tools menu under the message box).

Pass: ask Claude "What Picsha tools do you have?" and it lists tools such as search_assets, view_asset and contact_sheet.

Step 2: Add the photos

Paste this into the chat:

Add these three photos to my Picsha library and name them puppy.jpg, lighthouse.jpg and bear.jpg: https://picsum.photos/id/237/1600/1067 https://picsum.photos/id/870/1600/1067 https://picsum.photos/id/433/1600/1067

Claude calls trigger_url_ingest once per photo. Picsha downloads each file, makes thumbnails, and runs AI analysis on it: objects, scene, colours, text and faces.

Pass: Claude reports three asset IDs.

Step 3: Wait for processing

Analysis takes a few seconds per photo. Ask:

Are they finished processing?

Claude checks each asset with get_asset. If one is still queued or processing, ask again in a few seconds.

Pass: all three report status completed.

Step 4: Look at the library

Show me what's in my library.

Claude calls list_recent_assets. In Claude Desktop and claude.ai the results open as an interactive gallery inside the chat: a grid of thumbnails you can click to enlarge. On clients without that gallery, ask for a contact sheet instead and Claude returns one image with all three photos numbered.

Pass: you can see the three photos in the chat, not just their names.

Step 5: Search by what is in the picture

None of the photos has a caption, a tag or a useful filename beyond the one you gave it. Search on content:

Which one has an animal with fur that could be dangerous?

Claude runs search_assets in AI mode. Follow up with:

Show it to me full size.

That is view_asset: Claude sees the actual pixels and so do you.

Pass: the bear comes back, and Claude shows the full image.

Try a couple more: "the picture taken at night", "find the dog", "anything with the sea in it".

Step 6: Organise

Tag the bear "wildlife" and put the puppy and the bear in a collection called Animals.

Claude calls update_asset for the tag and create_dam_group plus add_assets_to_dam_group for the collection.

Pass: "Show me the Animals collection" returns exactly the puppy and the bear, and "find everything tagged wildlife" returns the bear.

Step 7: Get a web-ready version

Give me a 400 by 400 square crop of the puppy for a website, focused on its face.

Claude calls generate_render_url and returns a cdn.picsha.ai link. Open it: the crop is produced on demand by the Picsha CDN, and the URL is permanent.

Pass: the link opens and shows a square crop centred on the puppy.

Step 8: Tidy up

Move the lighthouse to the trash.

Claude calls delete_asset. Trashed assets leave search immediately and are kept for thirty days, so:

Actually, bring it back.

restores it with restore_asset.

Pass: after the delete, "show me the library" lists two photos; after the restore, three.

That is the whole loop: account, add, see, find, organise, deliver, tidy. Nothing in it needed the Picsha website after sign-up.

Part 2: Claude Code with an API key

Claude Code can also talk to Picsha through the same hosted endpoint, but it authenticates with an API key instead of OAuth, and because it has a shell it can upload files from your disk.

1. Sign in at picsha.ai and create a key under Admin → API keys.
2. Register the connector:

claude mcp add --transport http picsha-ai https://api.picsha.ai/v1/mcp --header "Authorization: Bearer <YOUR_PICSHA_API_KEY>"

3. In a Claude Code session, ask:

Upload ~/Desktop/photo.jpg to my Picsha library.

Claude calls get_presigned_upload_url, sends the file with curl, then calls complete_upload. From there steps 3 to 8 of Part 1 work unchanged.

Pass: the uploaded photo shows up in list_recent_assets with status completed.

If something does not match

• The Picsha tools do not appear in a chat. Claude caches a connector's tool list. Remove the connector and add it again, then start a new chat.
• Search finds nothing right after adding. The photo is probably still processing. Ask Claude to check its status.
• Results show as text, not a gallery. Your Claude client does not render MCP Apps yet. Ask for a contact sheet, or "show me number 2".
• Claude says a tool needs a billing method. Image generation (generate_image) is billed per image. Everything in this walkthrough is within the free allowance; generation is the one tool that asks for a card first.
• Adding a photo from your computer in claude.ai. Claude's chat cannot send file bytes to a connector, so from claude.ai photos are added by URL. Uploading from disk works from Claude Code (Part 2) or from any Picsha app.

What was happening underneath

Every step above was a Model Context Protocol tool call to https://api.picsha.ai/v1/mcp, scoped to the account you created in step 1. The same endpoint serves agent frameworks, Cursor, VS Code and your own code. The full tool list, the OAuth and API-key details, and the multi-tenant options are on the MCP Server page.