Urlbox README

Urlbox Screenshot MCP Server

Give your AI assistant a real browser for website screenshots. The Urlbox MCP server takes screenshots, makes PDFs and videos, extracts HTML, markdown and article text, compares pages, and manages your Urlbox projects, webhooks and usage.

Use the hosted server (recommended)

Connect your client to https://api.urlbox.com/mcp. Nothing to install.

• Claude (claude.ai and desktop): Settings, Connectors, Add custom connector, enter https://api.urlbox.com/mcp, then sign in to Urlbox.

• ChatGPT: add a connector with the URL https://api.urlbox.com/mcp, then sign in to Urlbox.

• Claude Code: claude mcp add --transport http urlbox https://api.urlbox.com/mcp, then run /mcp to sign in.

• Codex: codex mcp add urlbox --url https://api.urlbox.com/mcp, then codex mcp login urlbox to sign in.

• Cursor: add this to ~/.cursor/mcp.json:

  config.jsonCopy

  {
    "mcpServers": {
      "urlbox": {
        "url": "https://api.urlbox.com/mcp",
        "headers": { "Authorization": "Bearer YOUR_URLBOX_API_KEY" }
      }
    }
  }
  

Clients that can't sign in can send an API key as Authorization: Bearer <key>. An organisation API key (ubx_org_...) unlocks every tool. A project secret key works for the rendering tools only. Find your keys in the Urlbox dashboard.

Local bridge (this package)

Some clients can only start local servers. This package is a small local bridge: it runs on your machine over stdio and forwards everything to the hosted server, so you get exactly the same tools, always up to date.

{
  "mcpServers": {
    "urlbox": {
      "command": "npx",
      "args": ["-y", "@urlbox/screenshot-mcp"],
      "env": {
        "URLBOX_API_KEY": "your_api_key_here"
      }
    }
  }
}

Requires Node.js 20 or later.

The bridge adds one local tool, save_render, which downloads a render URL returned by any Urlbox tool and saves it to your computer. Just ask, for example "screenshot example.com and save it to my computer". Existing files are never overwritten.

Upgrading from 1.x

Your existing config keeps working: SECRET_KEY is still read and the package name and command are unchanged.

• Tools now come from the hosted server, so there are many more of them, and they keep improving without an update.
• render is still there. Its store_renders option and the download tool are replaced by save_render.
• Files are saved to ~/Downloads instead of ~/Downloads/urlbox-renders. Set URLBOX_DOWNLOAD_DIR to keep the old location.
• With a project secret key you get the rendering tools. Use an organisation API key to also manage projects, webhooks and usage.
• Node.js 20 or later is required.

Example prompts

• Take a screenshot of https://example.com without ads or cookie banners.
• Save https://urlbox.com as a tagged PDF with an outline and download it to my computer.
• Turn this article into markdown: https://example.com/blog/post
• How does https://example.com look on a phone?

Development

npm install
npm test

The tests run the bridge against a local fake server, so they need no Urlbox account.

License

MIT