Using ScreenFolio with Claude and Codex

You can let Claude Desktop or Codex look through your screenshots, so you can ask about them in the middle of a conversation or task. It uses MCP, a standard way for AI apps to talk to other apps on your Mac; this page just calls it a connection. You approve every assistant before it can see anything.

What an assistant can do

While connected, an assistant can:

Search your screenshot library, by words, by meaning, or by date.
Read screenshot details and text: when it was taken, the app it came from, a short description, and the text ScreenFolio recognized in it.
Open screenshots in ScreenFolio, so you see the one it found.
Copy a screenshot’s text to your Mac’s clipboard, and find screenshots taken just before or after one, or ones that look similar.

It can’t delete, move, rename or change your screenshots or files, change ScreenFolio’s settings, or search the web with Source Finder. It receives text and details, not the image itself. It only works while ScreenFolio is open.

Connect Claude Desktop

In ScreenFolio, click Claude Desktop under Assistants in the sidebar. You’ll find the same controls in Settings › Assistants, and in the “Use your screenshots with AI” step of setup if Claude Desktop is installed.
Click Install in Claude Desktop, then Set Up to confirm. If Claude Desktop isn’t on your Mac yet, the button reads Download Claude Desktop instead.
Fully quit Claude Desktop (not just close its window) and open it again. It only picks up the change after a restart.
Ask Claude about your screenshots. ScreenFolio will ask you to approve the connection.

Once it’s set up, the sidebar shows Ready and the button changes to Reinstall. Copy Server Command copies what Claude needs if you prefer to add ScreenFolio to Claude’s settings yourself.

Connect Codex

In ScreenFolio, click Codex under Assistants in the sidebar. You’ll find the same controls in Settings › Assistants, and in the “Use your screenshots with AI” step of setup if Codex is installed.
Click Install in Codex, then Set Up to confirm. This adds ScreenFolio to the settings the Codex app and the codex command-line tool share.
If Codex was already open, start a new session or restart it so it reads the new setting.
Ask Codex about your screenshots. ScreenFolio will ask you to approve the connection.

Once it’s set up, the sidebar shows Ready and the button changes to Reinstall. Copy CLI Command copies a codex mcp add command you can paste into Terminal instead.

Approving a connection

The first time an assistant connects after ScreenFolio opens, ScreenFolio asks “Allow “Claude Desktop” to use ScreenFolio?” (or “Codex”) and lists what it can do while connected.

Allow lets it connect until you quit ScreenFolio. You’ll be asked again next time.
Check Always allow this app before clicking Allow to skip the question in future. ScreenFolio shows a notification when an app you’ve allowed connects.
Don’t Allow, or closing the window, refuses the connection. The assistant sees no screenshots.
If the name isn’t one ScreenFolio recognizes, you’ll see “ScreenFolio doesn’t recognize this app. Allow it only if you just started it.” If you didn’t just ask an assistant for something, choose Don’t Allow.

Things to ask

“Find the error message from yesterday’s build.”
“Show me the screenshot of the flight confirmation and open it in ScreenFolio.”
“How many screenshots did I take last week?”
“What was I looking at just before this screenshot?”
“Find screenshots similar to that one.”
“Copy the text from that receipt to my clipboard.”
“Has ScreenFolio finished indexing my library?” Worth asking first if a search comes up short.

Checking status and stopping

The sidebar shows each assistant’s setup: Ready, Not configured, Not installed, or Update available. While an assistant is using ScreenFolio, the Assistants heading shows how many are connected. Claude and Codex connect only while a conversation or task is actually using ScreenFolio, so seeing no connection most of the time is normal.

Click an assistant in the sidebar and open the Overview tab to see whether ScreenFolio is running and who is connected. Restart starts over, and Stop cuts off every assistant until you click Restart or reopen ScreenFolio. The Tools tab lists what assistants can ask ScreenFolio for.

ScreenFolio doesn’t have a setting yet to undo Always allow this app. To stop an assistant from connecting, remove ScreenFolio from that assistant’s own settings (in Codex, codex mcp remove ScreenFolio), or use Stop.

Privacy

Everything stays on your Mac until you approve a connection. After that, the text and details the assistant asks for are sent to it, and it handles them under its own privacy policy. Before sending, ScreenFolio masks text that looks like a password, API key or token, and card or account numbers, so a question about a saved password may come back masked. Names, email addresses, phone numbers, links and addresses are not masked. See the privacy policy for more.

Troubleshooting

The assistant can’t see ScreenFolio: Make sure ScreenFolio is open; assistants can’t reach it while it’s closed. Check that the sidebar says Ready, then restart the assistant. Claude Desktop needs a full quit and reopen.
It says “Update available”: The assistant’s settings point to an old copy of ScreenFolio. Click Update Path, then restart the assistant.
The approval window didn’t appear: It opens in front of other windows while ScreenFolio is running. Answer it within about a minute, or the connection is refused and the assistant will need to try again. If you checked Always allow this app earlier, there’s no window, only a notification.
Searches miss screenshots I know are there: ScreenFolio may still be indexing. Ask the assistant whether indexing is finished, or wait and try again.
Install didn’t work: If macOS asks, click Grant Access and select the assistant’s settings file so ScreenFolio can add itself. Still stuck? Use the copy button to set it up by hand, or email support@screenfolio.app.