Let the agent open the screenshot itself

Hostbeam beams a screenshot from your Mac or your iPhone to your server and puts its path on your clipboard. The MCP server removes that last step: your agent asks for the screenshot and reads it, so there's nothing to paste.

dev@prod-box:~/app$ claude
› The layout breaks on mobile. Look at the screenshot I just beamed.
● hostbeam · latest_screenshot
✓ I see it. The nav wraps under 390px. Fixing.

Install it on the host

Install it on the server your agent runs on, not on your Mac. It needs Node 18 or later.

Claude Code

claude mcp add -s user hostbeam -- npx -y @hostbeam/mcp

-s user makes it available in every project on that host.

Codex

codex mcp add hostbeam -- npx -y @hostbeam/mcp

Any other MCP client

{
  "mcpServers": {
    "hostbeam": {
      "command": "npx",
      "args": ["-y", "@hostbeam/mcp"]
    }
  }
}

If the host can't reach npm, copy hostbeam-mcp.mjs from GitHub and run it with node. It has no dependencies. If you changed Hostbeam's folder for that host, give the server the same folder with HOSTBEAM_DIR.

Then just ask

Beam a screenshot and ask the way you'd ask a person: “what does the screenshot I just sent show?” The agent fetches your latest beam, with every file in it if you sent several, and knows how long ago it arrived.

What the agent can use

  • latest_screenshot: your most recent beam, as images.
  • list_screenshots: recent beams with names, sizes and times, without image data.
  • read_screenshot: one screenshot by name.

What it won't do

  • Read anything except the screenshots Hostbeam beamed into that one folder.
  • Read a file that isn't a picture. A PDF or a log you beam lands in the same folder, and the path Hostbeam copies gives the agent its location to open with its own tools.
  • Write, move or delete a file.
  • Follow a symlink, or read a folder that belongs to another user on the host.
  • Hand a model an image it can't accept. A HEIC photo, or a file over 3.75 MB, comes back as its path.

If it doesn't work

  • The agent says there's no screenshot. Check that claude mcp list or codex mcp list shows hostbeam, then ask the agent to use Hostbeam's latest screenshot.
  • Codex misses it right after opening. npx takes a few seconds to start the server, so wait a moment before your first message.
  • “Belongs to another user.” On a shared host, someone else created that folder first. Pick a folder of your own in Hostbeam, and set the same folder as HOSTBEAM_DIR.

Start a beam from a script

The agent reads beams. Something else can start one: a shell script, a launcher, a Shortcut, or the agent itself through a shell.

  • open hostbeam://beam beams the screenshot on your clipboard, exactly as the shortcut does.
  • open "hostbeam://host?id=my-server" changes which host beams go to, using the name you gave it in Hostbeam.
  • open -a Hostbeam shot.png beams a file. This one needs no permission and always works.

The two links work out of the box, and one switch turns them off: Preferences → General → Beaming → “Let other apps control Hostbeam”. If a link is ever ignored, that switch is the place to look. A link can only ever choose between hosts you have already added, and a web page cannot open one without your browser asking first. Needs Hostbeam 0.1.26 or newer.

Free and open source

The server is one MIT-licensed file, on GitHub and npm. It costs nothing, and beaming works as it always has, licensed or not.