walmart-invoice-mcp

MCP server for the Walmart Invoice Exporter browser extension (website). It lets Claude Code, Claude Desktop, and any other Model Context Protocol client read the Walmart order history you've already collected with the extension — ask Claude things like "how much did I spend on groceries in March?" or "find the order with the air fryer".

⚠️ The browser extension is REQUIRED. This server has no data of its own — it is only a relay to the Walmart Invoice Exporter browser extension. Without the extension installed, its AI access (MCP) toggle enabled, and the extension connected, no tool works. Install it first: github.harsh.al/Walmart-Invoice-Exporter.

Read-only by default, and always local-only. The server binds to 127.0.0.1 and only ever relays data between two processes on your machine: your MCP client and your browser. Nothing is uploaded anywhere. Out of the box, tools can only read orders the extension has already saved; if you additionally enable the extension's "Allow AI tools to collect data" toggle (off by default), AI tools may also start order collection and invoice fetching — in a background browser tab, using your own signed-in session, still entirely on your machine.

How it works

Remember: the extension is the only data source — this package cannot fetch, store, or serve anything on its own. A browser extension can't listen on a port, so this package is the meeting point:

Claude Code / Claude Desktop
        │  MCP over stdio
        ▼
walmart-invoice-mcp  ←— ws://127.0.0.1:8924 —→  browser extension (background)

Your MCP client spawns walmart-invoice-mcp; the extension (with the toggle enabled) connects out to it and answers queries from its on-device order database.

Related MCP server: monarch-mcp

Setup

1. Install the Walmart Invoice Exporter browser extension (required — nothing below works without it): github.harsh.al/Walmart-Invoice-Exporter.

2. In the extension — open the side panel → Settings → AI access (MCP) → enable the toggle. A pairing token is generated; hit Copy. Optionally also enable "Allow AI tools to collect data" if you want AI to be able to start collection and fetch invoices (off = read-only).

3. In your MCP client — add the server with that token.

   Claude Code (.mcp.json in your project, or claude mcp add):

   {
     "mcpServers": {
       "walmart-invoices": {
         "command": "npx",
         "args": ["-y", "walmart-invoice-mcp", "--token", "<paste token here>"]
       }
     }
   }

   Claude Desktop (claude_desktop_config.json): same block under mcpServers.

4. Start your MCP client. If tools report the extension isn't connected, open the extension side panel once — that wakes its background worker, which then connects within a few seconds.

Tools

All tools require the connected browser extension.

Read tools (available whenever the extension is connected):

Action tools (additionally require the extension's "Allow AI tools to collect data" toggle, off by default, and a browser signed in to walmart.com):

Options

Security

• Localhost only — the relay binds 127.0.0.1; it is unreachable from the network.

• Origin gate — page-initiated WebSockets always carry an http(s) origin; those are rejected outright, so a malicious web page can't even attempt auth. Only browser-extension origins (or native processes) get as far as the token check.

• Token auth — the first frame must carry the shared token generated in the extension; wrong token → disconnected. The token never appears in a URL.

• Read-only by default — out of the box the extension answers only read queries. Action tools (collection, invoice fetching) work only after the user enables the separate "Allow AI tools to collect data" toggle in the extension; nothing can ever delete saved data through MCP.

• Supply-chain cooldown — this repo installs dependencies with pnpm's minimumReleaseAge set to 14 days.

Development

pnpm install
pnpm test        # spawns the real binary, fakes the extension, drives a real MCP client

License

MIT