docs · tools

The local MCP server

browser-memory reaches your agent as an MCP server. If that phrase means nothing to you, this page is the whole thing from the beginning — what the protocol is, what “local” really means, what starts what, and what crosses the line between your machine and the internet.

What MCP is

The Model Context Protocol is a standard way for an AI application to talk to an external program that can do things. That is genuinely all it is: an agreed-upon vocabulary for “here are the tools I have” and “please run this one with these arguments”.

It exists because of arithmetic. Before it, every AI app that wanted to read your files, query your database or drive your browser had to implement each of those integrations itself, and every integration had to be written again for each app — the classic M×N problem. MCP turns it into M+N: a capability is implemented once as a server, and any client that speaks the protocol can use it. It is the same trick as a printer driver, or as LSP for editors.

Three roles, and it helps to keep them straight:

Note what the model does not do: it never speaks MCP itself. The host lists the server’s tools to the model as ordinary tool-calling options, the model picks one, and the host relays the call.

What “local” means

An MCP server can live in two places. Ours lives in the first, and the difference matters more than it sounds:

So a local MCP server is not a service you sign up for and not a daemon you keep running. It is a command line sitting in a config file. When your agent starts, it runs that command; when your agent quits, the process dies with it. In between, the two exchange JSON-RPC messages over the pipe.

For browser-memory the local part is the whole point: the tools it runs act as you, on sites where you are already signed in. That only works on a machine that has your browser on it.

The config entry, line by line

Every host stores this differently, but underneath it is the same three facts: a name, a command, and its arguments.

{
  "mcpServers": {
    "browser-memory": {
      "command": "npx",
      "args": ["-y", "browser-memory"]
    }
  }
}

• browser-memory — the label. It is how the host refers to this connection, and usually how its tools get namespaced in the UI.
• command — the executable to run. npx comes with Node.
• args — what to pass it. -y skips the “install this package?” prompt, which matters because nobody is there to answer it; browser-memory is the npm package to fetch and run. There is no global install to keep up to date.

Hosts differ in the wrapper only: most use the mcpServers key, VS Code uses servers and wants an explicit "type": "stdio", Codex uses TOML, and Claude Code has a command for it. You do not have to memorise any of that — one command writes the right shape into every agent it finds:

npx -y browser-memory install

It is idempotent, so running it twice is safe: it never overwrites an entry that is already there. To target a single host, name it — claude, cursor, vscode or codex:

npx -y browser-memory install cursor

It needs Node.js 18+ and Google Chrome already installed. Chrome is not optional: the server drives a real browser.

What happens when your agent starts

The handshake, in order, so nothing is mysterious:

Notice that no browser has opened yet. Chrome is launched lazily, by whichever call actually needs it — a discover is only a search over the index, so it never puts a window on your screen.

What this server exposes

Two groups. The first is the memory itself, and it is the part your agent uses all day:

The second group is a browser: bm_navigate, bm_click, bm_type, bm_snapshot, bm_screenshot, bm_network, bm_console, bm_wait_for, bm_tabs and a few more. These are the slow path — the ones the agent uses while learning an action it has no tool for. Once that action is saved, it stops touching them and calls run instead.

That is the shape of the whole product in one sentence: the bm_* tools are how something gets figured out, and run is how it never has to be figured out again.

The browser it drives

The server uses its own dedicated Chrome, with its own profile, rather than taking over the window you have your email open in. What that means in practice:

• You log in once, by hand. The first time a tool needs a site you are not signed into, you sign in yourself in that window. There are no credentials in any config file and none in a tool.
• The session persists. It lives in that Chrome profile, on disk, the same way a normal browser remembers you. Restarting the agent does not log you out.
• Cookies never travel. A request is issued from inside the browser that already holds the session, so the session data has no reason to leave the machine — and there is no token for you to paste anywhere.

More on how a tool uses that session, and what happens when it expires, under sessions.

The registry, and turning it off

On its own, the server would only know what your agent taught it. By default it also reads from the hosted registry — api.browser-memory.com — so a site somebody already worked out is fast on your very first run. This read is anonymous: no account, no sign-up, no login prompt. If the registry refuses or is unreachable, you are told once and everything keeps working with your local tools.

Where things sit:

To run fully local, with no registry and no events:

npx browser-memory config server off

config server on puts it back, and config set-url points it at a registry you host yourself.

Disconnecting it

npx -y browser-memory uninstall

…and restart the app, for the same reason as before: a server cannot unload itself from a live session. It only edits the host’s config — your learned tools in ~/.tool-memory and the Chrome profile are left alone, so reinstalling picks up where you left off.

When it does not show up

Next