Skip to main content
Glama

elsm-mcp — local MCP bridge for Easy Local Storage Manager

@elsm/mcp is a local MCP (Model Context Protocol) server that lets any AI agent — Claude Code, Cursor, Codex, Gemini CLI, ZCode, OpenCode or anything that speaks stdio MCP — read and write the real browser storage (localStorage, sessionStorage, cookies, IndexedDB) of the tab you're looking at, through the ELSM browser extension.

Requires the browser extension. The bridge has no storage access of its own — the extension is what reads and writes your browser. Install Easy Local Storage Manager from the Chrome Web Store (Firefox: build it from the extension repo and load extension/build/firefox unpacked).

Your AI agent (Claude, Codex, Cursor, ...)
        │ stdio (MCP protocol)
        ▼
  elsm-mcp  ← port 39231, pairing token in ~/.elsm-bridge/token
        │ ws://127.0.0.1:39231 (token + protocol version handshake)
        ▼
  ELSM extension (offscreen document / background page)
        │ privileged APIs (chrome.cookies, tabs, page access)
        ▼
  The active tab you are working on — its real storage

Install

Three steps, in this order — the bridge is useless until the extension is installed and paired.

1. Install the extension

Install Easy Local Storage Manager from the Chrome Web Store — that's where agent access, the pairing token and the Connected agents screen live. Firefox: build from the extension repo.

2. Run the bridge

npx @elsm/mcp --port 39231

The first run creates a pairing token at ~/.elsm-bridge/token (mode 0600). Open the ELSM sidebar → Agent access and paste that token once per browser.

3. Point your MCP client at it

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

The setup guide has the exact stanza for Claude Code, Codex, Cursor, ZCode, OpenCode and a generic mcpServers example, and npx @elsm/mcp --print-config prints them with your real paths.

Related MCP server: agent-chrome

Tools

Nine tools, scoped to the active tab's origin:

Tool

Plan

What it does

get_target

Free

Tab id, URL, origin, title of the active tab

list_storage_areas

Free

Origin, storage areas present, IndexedDB database names

read_storage

Free

Read localStorage/sessionStorage — one key, a prefix, or everything

read_cookies

Free

All cookies for the tab; values <redacted> unless raw-value consent is granted in the UI

read_indexeddb

Free

Cursor-paged, JSON-safe read of an object store

export_state

Free

Snapshot localStorage/sessionStorage + cookie metadata (always redacted)

write_storage

Pro

Write {key, value} entries; every write lands in the sidebar changelog

delete_keys

Pro

Delete keys from localStorage/sessionStorage

clear_area

Pro

Wipe an area — needs confirm: true on a retry after the user armed Clear-all in the sidebar (60s window)

Free plans are read-only and capped at 50 agent calls per day; Pro is unlimited. On the extension's Connected agents screen you can see every agent that called in (last used, total calls, last action), block one, or revoke it.

Safety model

  • The WebSocket server binds loopback only (127.0.0.1) — never a routable interface.

  • Every connection must authenticate with the pairing token as its first frame; non-hello frames are dropped, and token/protocol mismatches are hard refusals (no downgrade).

  • Token comparison is hashed and constant-time; the token file is written atomically with mode 0600.

  • No code: injection — all page access goes through chrome.scripting.executeScript with functions and JSON args.

  • The bridge only ever talks to loopback. Note that your agent itself may send retrieved data to its LLM provider; that's between you and your agent.

CLI

elsm-mcp [--port <n>] [--token-file <f>] [--print-config] [--selftest]
  • --port — fixed WS port (default 39231)

  • --token-file — pairing token file (default ~/.elsm-bridge/token, or ELSM_TOKEN_FILE)

  • --print-config — print paste-ready config stanzas for common clients

  • --selftest — run the internal smoke test (real WS roundtrip: handshake, auth refusal, protocol-mismatch refusal, pre-auth frame dropping, agent attribution, session replacement) and exit

Development

bun install
bun run build      # tsc → dist/
bun run typecheck
bun run test       # dist/cli.js --selftest

The wire contract with the extension is duplicated by design: the canonical protocol types live in src/types.ts, and the ELSM extension repo keeps a hand-mirrored copy (extension/src/shared/types/agent-bridge.types.ts). Change both in the same change and bump the protocol version in both files — mismatches are refused at the handshake.

License

MIT

Available Tools

9 tools
clear_areaA

Clear an entire area (every key) for the active tab's origin. Destructive: requires BOTH (1) confirm: true in the call — pass it on the retry after receiving needsConfirmation — and (2) the user pressing 'Clear' in the ELSM sidebar Agent panel within 60s before the retry. Params: area (required), confirm (boolean).

Inputs: area (required), confirm.

delete_keysC

Delete keys from localStorage or sessionStorage on the active tab's origin. Params: area (required), keys (required array).

Inputs: area (required), keys (required).

export_stateA

Export the storage snapshot of the active tab's origin: origin, localStorage, sessionStorage, and cookie metadata (cookie values always redacted). Params: rawCookieValues (boolean, ignored — kept for compatibility).

Inputs: rawCookieValues.

get_targetA

Describe the active target the agent is operating on: tab id, URL and origin, title. No secrets.

Inputs: no named parameters.

list_storage_areasA

List what the bridge can operate on for the current target: origin, storage areas present, IndexedDB database names.

Inputs: no named parameters.

read_cookiesA

Read all cookies visible to the active tab (name, domain, path, secure, httpOnly, sameSite, session). Params: rawCookieValues (boolean) — values are returned as "" unless the user has explicitly granted raw-value consent in the extension UI; without consent the call still succeeds but values stay redacted.

Inputs: rawCookieValues.

read_indexeddbA

Cursor-paged, JSON-safe read of an IndexedDB object store on the active tab's origin. Params: db (required), store (required), cursor (number offset from a previous call's nextCursor), limit (default 200, max 1000).

Inputs: db (required), store (required), limit, cursor.

read_storageA

Read keys from localStorage or sessionStorage of the active tab's origin. Params: area (required), key (single key) or prefix (all keys beginning with the prefix); omit both for everything. (Cookies are not an area here — use read_cookies.)

Inputs: area (required), key, prefix.

write_storageA

Write entries into localStorage or sessionStorage of the active tab's origin. Params: area (required), entries ([{key, value}] as JSON-serializable strings). Every write is appended to the sidebar changelog so the user sees it.

Inputs: area (required), entries (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 9 tools

    Disambiguation4/5

    Most tools target clearly distinct operations (read_cookies vs read_storage vs read_indexeddb vs get_target vs list_storage_areas), and descriptions explicitly disambiguate, e.g. read_storage notes 'Cookies are not an area here — use read_cookies.' The main overlap is export_state, which produces a full snapshot of the same storage areas read_storage reads, so an agent could reasonably pick either for 'dump everything.'

    Naming Consistency5/5

    All nine names follow a consistent snake_case verb_noun convention (read_cookies, write_storage, delete_keys, clear_area, export_state, etc.), including the multi-word list_storage_areas and read_indexeddb. No style mixing.

    Tool Count5/5

    Nine tools sit comfortably in the 3-15 sweet spot and each maps to a concrete capability (read/write/delete/clear across storage areas, cookies, IndexedDB, target introspection, export). Nothing feels padded or missing at the count level.

    Completeness4/5

    Storage lifecycle is well covered (read/write/delete/clear/list plus export), but the surface is asymmetric: cookies and IndexedDB are read-only with no write/delete counterparts, likely by design for safety. An agent could still be blocked if it needs to set a cookie or modify an IndexedDB store, though those are arguably out of scope for a read-inspection bridge.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI clients to control the user's already-open, logged-in browser pages in real time over a local WebSocket channel, without Playwright, Puppeteer, Selenium, or any browser driver. Exposes tools for navigation, semantic page snapshots, clicking, form filling, JavaScript evaluation, screenshots, network monitoring, cookie handling, and tab management via the CDP.
      20
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Lets local AI agents drive the Chrome browser a user already has open, including signed-in sessions, by listing tabs, reading page text and actionable elements, then clicking, filling, selecting, scrolling, navigating, and capturing viewport screenshots without exporting cookies. Runs as a dependency-free local stdio process over Native Messaging, with per-tab leases, automatic reconnection, and pause/write-action controls.
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes a governed, OAuth-gated suite of 38 tools that let web AI assistants like Claude, ChatGPT, and Grok work directly on your local machine — reading and editing files, running whitelisted shell commands, searching, querying SQLite, driving browsers and DevTools, managing background tasks and localhost services, and controlling Git, clipboard, notifications, and Postman. This lets users build, debug, and maintain projects, inspect databases and local APIs, and check on long-running jobs from a browser or phone without granting unrestricted shell access.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Lets AI coding tools drive the real, already-logged-in Chrome browser over local stdio—snapshotting and reading pages, clicking, typing, managing tabs, capturing screenshots, and inspecting network, console, storage, and cookies—without opening a remote-debugging port. It installs as a Chrome extension plus native-messaging bridge, so agents work in the user's authenticated sessions while passing bot detection.
      1 npm
      ISC