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.

Tools

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

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.

Links

• Extension (Chrome Web Store): cnmpfamlolfgahjambofnemellgdddia
• Setup guide: easylocalstorage.dev/docs
• Extension source: nowshad-hossain-rahat/easy-local-storage-manager
• Bridge source: nowshad-hossain-rahat/elsm-mcp

License

MIT