٢٦ أغسطس ٢٠٢٦ · 12 دقيقة للقراءة

خادم MCP في Screenshot Bro: أتمتة لقطات App Store

إجابة سريعة: Open Screenshot Bro on your Mac, switch on Settings ▸ Automation ▸ Enable MCP server, then paste the Copy Agent Prompt into Claude Code, Claude Desktop or Cursor. The client connects to a local server at http://127.0.0.1:8722/mcp with a bearer token, and your agent gets 26 tools that create projects, lay out rows and shapes, import screenshots, translate text, render previews it can actually see, export PNGs, and sync a finished set to App Store Connect — all through the same undoable actions you use by hand.

Screenshot Bro ships an MCP server inside the Mac app. Turn it on and an AI assistant — Claude Code, Claude Desktop, Cursor, or anything else that speaks the Model Context Protocol — can drive the editor directly: create the project, size the rows, place the headlines, pull in your screenshots, translate them, look at what it made, and push the finished set to App Store Connect. You watch it happen on the canvas, and every change it makes is undoable with ⌘Z.

This guide covers the whole thing: what the server is, how to turn it on, how to connect each client, what all 26 tools do, the prompts that get good results, the sandbox rule that trips up screenshot imports, and what the server deliberately cannot do. Everything below was checked against Screenshot Bro 4.2 in August 2026.

What the Screenshot Bro MCP Server Actually Is

MCP — the Model Context Protocol — is a standard way for an AI client to discover and call tools that some other program provides. Screenshot Bro implements the server half. It is not a cloud service and not a separate binary you install: it is the running Mac app, listening on a loopback port, exposing its own editing actions as tools.

Two consequences of that design are worth internalising before you start. First, the app has to be open — the agent is not talking to a headless service, it is remote-controlling a window on your screen. Second, agent edits are ordinary edits: they go through the same undo transactions and the same autosave as your own clicks, so a bad instruction is one ⌘Z away from being reversed, not a corrupted file.

What You Need Before You Start

• Screenshot Bro 3.6 or later on macOS 15 or later. The server shipped in 3.6, the App Store description tools in 3.7, and the screenshot-sync tools in 3.9.
• An MCP client that supports streamable HTTP servers with custom headers — Claude Code, Claude Desktop and Cursor all do.
• Raw screenshots if you want the agent to work with real content rather than a template mockup. PNG or JPEG, at the pixel size of the device you are targeting.
• Optional: an App Store Connect API key configured in Settings ▸ App Store Connect. Without it the four App Store tools return an error; everything else works fine.

Step 1: Turn the Server On

Open Settings ▸ Automation and switch on Enable MCP server. It is off by default and nothing listens until you flip it. Once enabled it stays enabled and starts automatically the next time you launch the app.

The Status row underneath tells you where you stand: Not running, Starting…, or running on a port. When it reports a port, a Connection section appears with the Server URL, a masked Access Token, and three buttons — Copy Agent Prompt, Copy Configuration (JSON), and Regenerate Access Token.

Step 2: Connect Your AI Client

The one-minute way: Copy Agent Prompt

Click Copy Agent Prompt and paste it into your assistant. It is a plain-English instruction that already contains your URL and token, and it tells the agent to register the server itself and then reconnect. Most clients can do that without you editing a file:

Add an MCP server named "screenshot-bro" to your configuration so you can
control the Screenshot Bro app.

It uses streamable HTTP transport:
- URL: http://127.0.0.1:8722/mcp
- HTTP header: Authorization: Bearer <your access token>

Use whatever method your MCP client supports (a config-file entry or an
"mcp add" command). After adding it, reconnect so the screenshot-bro tools
load, then list them to confirm.

The token in the real prompt is filled in for you. Treat that pasted text as a secret — it is a working key to your app.

Claude Code

If you would rather run the command yourself, Claude Code registers HTTP servers from the CLI:

# Add the server (run it from the folder you want the tools in)
claude mcp add --transport http screenshot-bro http://127.0.0.1:8722/mcp \
  --header "Authorization: Bearer PASTE_YOUR_ACCESS_TOKEN"

# Confirm it connected
claude mcp list

Add -s user if you want the server available in every project rather than just the current folder.

Claude Desktop, Cursor, and other MCP clients

Click Copy Configuration (JSON) and paste the entry into your client's MCP configuration file. It is a standard mcpServers block, so it works anywhere the format is supported:

{
  "mcpServers": {
    "screenshot-bro": {
      "type": "http",
      "url": "http://127.0.0.1:8722/mcp",
      "headers": {
        "Authorization": "Bearer PASTE_YOUR_ACCESS_TOKEN"
      }
    }
  }
}

Restart the client afterwards. Clients read MCP configuration at launch, so an edit made while the app is open usually does nothing until it reconnects.

Check that it worked

Ask the assistant to list your screenshot-bro tools. You should get 26 of them, starting with list_templates and list_projects. If the list is empty, the client connected to nothing — see the troubleshooting table at the end.

The 26 Tools, Grouped

You never call these by hand; the agent picks them. But knowing what exists is what lets you write a prompt that maps cleanly onto them instead of asking for something that has no tool behind it.

Two conventions run through all of them. Every object has a UUID — projects, rows, template columns, shapes — and get_project is how the agent learns them, so a well-behaved agent calls it early and again after structural changes. And every coordinate is in model space: pixels of the target screenshot, not points on your screen. On a 1290×2796 row, y: 180 means 180 px from the top of the exported image.

Step 3: Build Your First Set From a Prompt

Open Screenshot Bro so you can watch, then give the assistant something concrete. Vague prompts produce vague layouts; the tools are precise, so the prompt may as well be:

Using the screenshot-bro tools:

1. Create a project called "Habit Tracker Launch" from a bundled template.
2. Make the first row 1290x2796 with three screenshot columns.
3. Give the row a dark navy background with a subtle vertical gradient.
4. Put one headline near the top of each column: "Build the habit",
   "See the streak", "Never lose a day" — white, centred, large.
5. Render a preview of the row and show it to me before doing anything else.

A competent agent will run roughly this sequence:

list_templates       -> pick a starter template
create_project       -> name + template_id, becomes the active project
get_project          -> row ids, template ids, sizes, locales, shape ids
update_row           -> size 1290x2796 + background_gradient
add_template         -> third column
add_shape (text) x3  -> one headline per column
update_shape         -> font_size, color, text_align, y position
render_preview       -> returns a PNG the model can look at

The last line is the one that changes everything. render_preview returns an actual downscaled PNG of the row — up to 1200 px on the long side, 700 by default — as an image the model can look at. That closes the loop: the agent can see that a headline is colliding with the device frame, and fix it, instead of writing coordinates blind. If your prompt does not ask for a preview, ask for one anyway before you accept the result.

Prompting tip: tell it to preview after each visual change, not once at the end. The cost is a couple of seconds and it is the difference between a layout that is roughly right and one that is actually right.

Importing Your Real Screenshots (and the Sandbox Rule)

import_screenshots takes a row id and a list of absolute file paths, and fills that row's device-holding columns in order, creating extra columns if you pass more images than there are slots. It replaces whatever was there — you cannot target a single column, so re-import the whole row's images in the order you want.

The catch: Screenshot Bro is sandboxed. It can read its own container and folders you have granted it through a file dialog, but it cannot read arbitrary paths — including /tmp and the scratch directories coding agents like to use. A path that is perfectly readable for your agent may be invisible to the app. When that happens the tool returns an error naming the folder it can read; stage the files there and retry:

# The app is sandboxed: it reads its own container and folders you granted it,
# not arbitrary paths. Stage the shots where it can definitely read them.
# The exact folder is printed in the tool's error message — use that one if
# yours differs.
STAGE=~/Library/Containers/xyz.tleskiv.screenshot/Data/tmp/inbox
mkdir -p "$STAGE"
cp ~/Desktop/raw-shots/*.png "$STAGE"/

The same rule applies in reverse to exports, which is why export_project defaults to a folder it knows it can write.

Localizing Screenshots With an Agent

This is where an agent earns its keep, because translation is exactly the kind of tedium worth handing over. Two tools do the work: add_locale registers a language on the project (any code — de-DE, fr-FR, ja, pt-BR), and set_translation writes one text shape's copy for one locale.

Add de-DE, fr-FR and ja to the project. For every text shape in row 1,
translate the English copy and write it back with set_translation — keep each
headline under 30 characters so it doesn't wrap, and render a preview of the
German row when you're done so I can check the line breaks.

Three rules to know before you point a model at your copy:

• The model does the translating, not the tool. set_translation stores exactly the string it is handed. The app's own on-device auto-translate is a UI feature; over MCP, the quality of the German is the quality of the model.
• The base locale is edited differently. set_translation refuses the base locale — that text lives on the shape itself, so it is update_shape's text field. The base locale also cannot be removed.
• Length is the real risk. German and French run 20–35% longer than English and will wrap or overflow a headline box that fits in English. Give the agent a character budget in the prompt and make it render a preview of the longest language.

Exporting

export_project writes the active project's screenshots as PNG or JPEG and returns the exact file paths it wrote. Pass locale to export a single language, or leave it off for all of them. Pass folder_path only if you know the app can write there; otherwise omit it, let the app export to its own temp folder, and have the agent copy the files wherever you actually want them — it is not sandboxed, so it can.

Driving App Store Connect From the Agent

With an App Store Connect API key configured, four more tools open up. The two metadata tools are straightforward: get_app_store_metadata returns every App Store version — one per platform — with its per-locale descriptions, which is also how the agent discovers the exact locale codes your listing uses. Then update_app_store_description writes new descriptions back. That tool applies what you give it and does not translate anything itself, so the agent must supply one already-written description per locale; locales that do not exist on a version are reported as skipped rather than created.

Screenshots are deliberately harder, because they overwrite a live listing. The flow is two-step and cannot be short-circuited:

preview_app_store_screenshot_sync
  -> plan_id, expiresAt (15 minutes), one set per version/display type/locale,
     a contact sheet image, and a list of what would be added, reordered,
     kept or removed — nothing has touched App Store Connect yet

apply_app_store_screenshot_sync
  -> plan_id + the set_ids you approved + confirm: true
     (leave confirm out and the call is rejected)

The preview renders your project, compares checksums and ordering against what is already on App Store Connect, and reports what would change — including a contact sheet image so the agent can look at the screenshots it is about to upload. Rows or locales it cannot match confidently are reported and skipped rather than guessed at. Apply then re-validates everything, preserves assets that already match, and verifies the final order. Plans expire after 15 minutes; if you deliberate longer than that, preview again.

Worth saying plainly: this step publishes to a real listing. Read the preview before you approve it, the same way you would read a diff.

Prompt Patterns That Work

• Give it the snapshot first. "Call get_project and tell me what rows and locales exist before changing anything." It stops the agent inventing ids.
• Anchor to pixels. "Headline at y=160, 96 pt, 88% white, centred" beats "put a nice title at the top".
• Demand previews. "Render a preview after each row you finish."
• Batch the boring parts. "Add these six locales and translate every text shape in rows 1 and 2."
• Ask for a plan on anything destructive. "Preview the App Store sync and list what would change — do not apply it."
• Let it iterate on one thing. "This headline wraps in German — shorten it and re-render until it fits on one line."

Security: What the Token Protects, and What It Doesn't

• The listener binds to 127.0.0.1. Other machines on your network cannot reach it, and neither can the internet.
• Every request must present the access token, which is generated on first enable and kept in your Keychain. Without it another local process cannot quietly drive the app.
• Anyone holding the token can control the app while the server runs. Do not paste it into a shared config file, a screenshot, or a repository. Regenerate Access Token issues a new one and restarts the server; every client using the old token must be updated.
• Turning the server off is instant and total — no listener, no tools, no connections.
• Enabling the server has an analytics footprint: the app records that MCP sessions happened and which tool names were called, as counts. Your project text and images are not part of that. The exact event list is in the privacy policy.

Troubleshooting

What the MCP Server Can't Do

Being clear about the edges saves you a wasted afternoon:

• It is not a CLI or a hosted API. There is no screenshotbro command and no endpoint on the internet — the server is local to a running Mac app.
• It does not run headless or in CI. The app must be open. For unattended pipelines, see how this compares with fastlane.
• macOS only. The iPad and iPhone builds do not host a server.
• It cannot capture screenshots for you. There is no Simulator capture tool in the shipping app; you bring images you already took.
• It cannot target a single screenshot column on import. Re-import the whole row's images in order instead.
• Google Play uploads are not exposed over MCP. The App Store Connect tools have no Play equivalent yet — that upload stays in the UI.

Is It Worth Using?

For a first draft of a listing, yes — an agent that can create rows, place text, translate six languages and look at its own output does in a few minutes what is otherwise an hour of nudging boxes. For a listing you have already tuned by hand, it is better as an assistant for the repetitive parts: adding a locale, restating a headline across ten columns, checking which screenshots actually differ from what is live.

The honest framing is that MCP does not replace judgement about what your screenshots should say — see screenshot copywriting for that part. It removes the mechanical distance between deciding and seeing.