Let the agent open the screenshot itself

Hostbeam beams a screenshot 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.

~/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.
  • 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.

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, free tier included.