pomerado README

The project's README from github.com/Pomerado/pomerado. As one markdown file: README.md.

Pomerado

Turn websites into MCP integrations your agent can rely on.

License MIT npm version Node 24.21 or later in Node 24

How it works · Get started · Create an integration · Use your integration · Open source and Cloud · Docs · Discord · Contributing

What Pomerado does

Pomerado builds MCP integrations for websites, including sites without an API.

How it works

┌──────────────────────────────────────────────────────────────────────────┐
│  explore the site → complete your example → generalize → agent calls it  │
└──────────────────────────────────────────────────────────────────────────┘

For more details, see How it works.

Get started

Prerequisites

Install Pomerado and the Chromium build it drives.

npx -y -p pomerado pomerado-mcp --help
npx -y -p pomerado playwright install chromium

On Linux, add --with-deps after install if Chromium's system libraries are missing.

Pomerado runs as a standard MCP stdio server. Clients that read an mcpServers file use this entry.

{
  "mcpServers": {
    "pomerado": {
      "command": "npx",
      "args": ["-y", "-p", "pomerado", "pomerado-mcp", "mint", "--root", "/absolute/path/to/pomerado-integrations"]
    }
  }
}

Add Pomerado to your client with the command or file below.

Client Add Pomerado
Claude Code claude mcp add --scope user pomerado -- npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations
Codex codex mcp add pomerado -- npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations, then add env_vars
Gemini CLI gemini mcp add -s user -e 'OPENAI_API_KEY=$OPENAI_API_KEY' pomerado npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations
Cursor Add the entry to ~/.cursor/mcp.json
VS Code code --add-mcp '{"name":"pomerado","command":"npx","args":["-y","-p","pomerado","pomerado-mcp","mint","--root","/absolute/path/to/pomerado-integrations"]}', or add the entry to .mcp.json in your workspace
Claude Desktop Add the entry to claude_desktop_config.json

Each client passes environment variables its own way. Client settings covers the key and the timeouts for every client above.

To confirm the setup, ask your agent which Pomerado tools it has. It should list mint, get_job, provide_input and cancel_job.

Let your agent set it up

If you'd rather not run these steps yourself, paste this into your agent.

Set up Pomerado for me by following https://raw.githubusercontent.com/Pomerado/pomerado/main/docs/agent-setup.md

Your agent checks your Node version, installs Chromium and adds Pomerado to the client it runs in. It asks before changing anything you didn't mention, and it never asks for your API key in chat.

Create an integration

Ask your agent to create an integration with Pomerado. We call this minting. A good request names the site, describes the task in plain language and says whether the integration should only read or also make changes.

Use Pomerado to create an integration named example_reader that reads the main heading from https://example.com. Keep it read-only.

Your agent runs the mint with four tools.

Authority decides what an integration is allowed to do, so choose it deliberately. Your agent picks one when it calls mint, and the tool tells it to ask you before choosing write.

Pomerado types your login only on the site, or on a sign-in address you pass in authenticationOrigins when you call mint. A sign-in form whose fields or submit go to any other website is refused before anything is typed. A sign-in whose pages are on another website doesn't publish, even one you pass there. Pomerado doesn't ask about other addresses, and it doesn't check where the page's own scripts send what you typed.

Names start with a lowercase letter and use only lowercase letters, digits and underscores. The integration's folder must not exist yet. Each mint gets 20 minutes of active work, and time spent waiting for your answers doesn't count against it.

Use your integration

When minting finishes, Pomerado saves the integration as a folder of source code and returns its paths.

pomerado-integrations/example_reader/
├── src/                 Generated operation modules
├── pomerado.json        Entrypoint, input and output schemas, and the questions a run may ask
├── auth-fill.json       Sign-in screens a build that signed in recorded, with no value
├── deployment.json      Tool name, description, URL, task, authority and sign-in origins
├── mcp.mjs              Launcher for the shared Pomerado runtime
├── mcp.json             Standard MCP server entry, with no key
└── README.md            Add commands for each MCP client
  1. Open the integration's README.md. It has the add command for each major client with your paths already filled in
  2. Add the server with that command. Skip the key setup. Running an integration makes no model request, so only minting needs OPENAI_API_KEY
  3. Reload your client and ask your agent to use the integration

Use example_reader to read the page heading.

Each integration appears to your agent as its own MCP server.

Open source and Pomerado Cloud

This repository is the complete Pomerado core, released under the MIT license. Everything you need to mint integrations and run them yourself is here, with no Pomerado account required.

Pomerado Cloud runs this same core as a managed service. It adds the operations that production use needs.

Documentation for humans and agents

Repository guide

Path Contents
typescript/src/ Minter, Guardian, runtime, browser helpers and the local MCP host
typescript/authoring/ Shared prompts and examples, with sections a host can replace
typescript/tests/ Unit tests and browser tests with local fixture sites
tools/ Build helpers and the CI scans
docs/ Guides for users, agents and maintainers
third-party/ Licenses for adapted third-party code

How it works lists each module under typescript/src/.

Community

Join the Pomerado Discord to get help, share integrations you build, and discuss contributions.

Contributing

License

Copyright (c) 2026 Pomerado AI, Inc. Licensed under the MIT License (MIT). See LICENSE.

Versions 0.1.2 and earlier were published under the GNU Affero General Public License version 3 only (AGPL-3.0-only).

Third-party code keeps its own license. The Guardian policy in typescript/src/guardian/upstream-policy.md is adapted from OpenAI Codex under the Apache License 2.0. Its license and notice are in third-party/codex/ and ship with the npm package. The accessible name computation in typescript/src/destinations/accessible-name.ts is adapted from Playwright under the Apache License 2.0. Its license and notice are in third-party/playwright/ and ship with the npm package.

Star History

Star History Chart

pomerado (Pomerado/pomerado)

Searching Database…

915 ·GitHub
Pomerado
What is this?Pomerado turns any website, including ones without an API or behind a login and two-factor auth, into a deterministic MCP integration your AI agent can call as a tool, built from just a plain-language description of the task instead of a recorded HAR file.
Is this an open-source tool I run myself, or a hosted service?This repo is the full open-source MIT core: a minter that drives a real Chromium browser, a Guardian reviewer and a local MCP host, all run on your own machine with no account needed. Pomerado Cloud is a separate paid managed version of the same core that adds hosting, OAuth and bot-protection handling.
How do I get it running?Install and register it as a local MCP stdio server with your client, e.g. 'claude mcp add --scope user pomerado -- npx -y -p pomerado pomerado-mcp mint --root ~/pomerado-integrations'. Once added, you ask your agent to 'mint' an integration by naming the site, describing the task, and saying whether it should only read or also make changes.
What do I need before I start?You need macOS or Linux, Node 24.21 or later, an MCP client that can run local servers (Claude Code, Codex, Cursor, VS Code, Claude Desktop or Gemini CLI), and an OpenAI API key, since Pomerado uses OpenAI models only during minting, not while running finished integrations.
Any catches before I start minting?Each mint job gets only 20 minutes of active work (time spent waiting for your answers doesn't count), it only runs on macOS or Linux (no Windows), and a sign-in form is refused outright if its fields or submit target point to a different domain than the one you're minting against.
Where do my login details go when an integration signs in?Pomerado only types your credentials into the site itself or into a sign-in address you explicitly allow via authenticationOrigins; it never saves the login, code or answer, and it refuses sign-in pages that point anywhere else.
What is minting?Minting is the build process: Pomerado's agent drives a real Chromium browser to perform the described task once, then its Guardian component reviews every browser action and the final generated source code before saving the integration.
What is the difference between read and write authority?Read integrations only look at a site, while write integrations can submit forms or make bookings; the agent must choose write deliberately, and Pomerado asks before switching a read mint to write mid-job.
Why not just use a computer-use agent instead?Minted integrations replay a fixed, reviewed sequence of steps rather than having an agent click through the live page each time, which the README says makes them much faster and more reliable than computer-use approaches.
What does Pomerado Cloud add over the open-source core?Pomerado Cloud adds hosting for your integrations and their jobs, OAuth brokerage and saved logins, access control over who can use each integration, a managed browser fleet that handles bot protection, and automatic breakage detection and repair when a site changes.
What are similar projects?freeCodeCamp, openclaw, rea, developer-roadmap, deepseek-harness, opencode, vue, n8n
Which topics is it in?typescript
Creator
Pomerado
Size
10.1 MB
Stars
915
Updated
CommitOct 27Releasev0.4.0-canary.399Oct 26
Age
21d
Commits · 90 Days