Skip to Content
GuideAutomate with AI (MCP)

Automate with AI (MCP)

Screeny for Mac ships with a built-in MCP (Model Context Protocol)  server, a local-only web server that lets AI clients like Claude, Claude Code, Cursor, VS Code, and Codex drive Screeny directly.

Once connected, you can ask your agent things like:

  • “Frame the screenshot on my Desktop in an iPhone 17 Pro with a gradient background”
  • “Batch-render this folder of App Store screenshots with my ‘App Store’ preset”
  • “Make a 3D mockup of home.png, turned 30 degrees, and show me a preview first”
  • “Turn hero.png into a 3D video that feels like a keynote reveal: start from behind, end straight on”
  • “Make the iPhone Duo open, with cover.png on the outside and my recording playing inside”
  • “Create a project called ‘Launch’ with these three screenshots, then open it”
  • “Switch what I have open to 3D and export it as it is”

The most reliable way to get consistent results is to save a preset and ask for it by name. See Prompting Screeny. For prompts you can copy, with the picture or video each one produced, see the Prompt Reference.

Enable the server

  1. Open Screeny for Mac, then press ⌘, to open Settings
  2. Click Automation in the toolbar
  3. Turn on MCP Server

A green dot appears underneath with the server address, normally http://127.0.0.1:9410/mcp. Click the row to copy it.

The Automation tab of Screeny for Mac's Settings window, with the MCP Server toggle switched on and the server address http://127.0.0.1:9410/mcp shown below a green dot

The default port is 9410, a nod to 9:41, the time on every Apple status bar. If it’s taken, Screeny picks the next free one (9411–9419), so check Settings for the actual URL.

Connect your client

Screeny must be running with the MCP server enabled. Pick your client:

Point Claude Code at the server address. One command, nothing to install:

claude mcp add --transport http screeny http://127.0.0.1:9410/mcp

Check the address in Settings → Automation first. The command hardcodes the port, so if 9410 was taken and Screeny landed on 9411–9419, use the port shown there instead.

Or install the plugin. Same sixteen tools, and it finds the port itself, so a busy 9410 never breaks it. It also carries a skill that teaches Claude Code how to use the tools well: look up the valid devices and colors first, preview before exporting, ask for a folder when a file can’t be read.

claude plugin install screeny --marketplace lkolebka/screeny-claude-plugin

The plugin needs Node.js  18 or later. You can also run /plugin install screeny --marketplace lkolebka/screeny-claude-plugin from inside a session.

Use the URL or the plugin, not both, or every tool is listed twice.

What the agent can do

The server exposes sixteen tools, in five groups:

  • Discover. List devices, 3D models, lighting setups and camera movements; list your presets and projects; read a project or what is open in the editor; check your credits.
  • Render. Image mockups (up to 10 per call) and video mockups, flat or in 3D, plus a free inline preview so the agent can look at its own framing, or at a whole animation on one contact sheet, before it exports.
  • Projects. Create a project, change its look, animation or screenshots, rename, duplicate, move, export, import and delete.
  • The app on screen. Open a project in the editor and change what is open, live, while you watch.
  • Files. Request access to a folder.

For the full parameter tables, the device and color list, and troubleshooting, see the MCP Tools Reference. For writing the prompts themselves, see Prompting Screeny and the Prompt Reference.

See it in action

Here’s what a real request looks like end to end, in Claude Code.

1. Ask for a mockup. Just describe what you want, attach or point to the screenshot, and tell your agent where to save it:

A Claude Code session where the user asks Screeny to create a mockup with the current preset and save it to the Desktop; Claude reports that Screeny needs permission to access the Desktop folder and will trigger the macOS access prompt

2. Grant the folder Screeny asks for. The first time an agent needs a folder it hasn’t been granted, macOS shows its native picker, pre-navigated to that folder: click Grant Access, pick a different folder, or cancel:

The native macOS folder access panel, pre-navigated to the Desktop, with a Grant Access button and the text "AI tools will be able to read the folder you choose and save new files into it."

3. Done. The agent retries automatically and reports back with the saved file:

The same Claude Code session confirming access was granted and the mockup was saved to the Desktop, listing the device, bezel color, background, and zoom used from the current preset

Folder access: your AI asks, you approve

Screeny is sandboxed. An agent can only reach folders you have explicitly approved. When it needs access, Screeny shows the native macOS folder picker and you decide, as above. Inside a granted folder, exports only ever create new files: Screeny never overwrites, modifies, or deletes anything.

You can also grant folders ahead of time, without waiting for an agent to ask. Go to Settings → Automation → Folder Access and click Add Folder. Every granted folder is listed there and can be revoked at any time:

The Folder Access panel open over Screeny's Settings window, listing the granted Desktop and Downloads folders and an Add Folder button

Everything renders locally on your Mac, the server only listens on 127.0.0.1, and MCP exports use the same credit system as the app (1 per image, 3 per video). Previews and everything that creates or changes a project are free.

The Claude plugin is one small bridge between Claude and the app, and its source is public . It talks only to Screeny on your Mac: no other network request, no files read or written.

Last updated on