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.

Setup

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

1. 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).

2. 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.

3. 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):

Tool	What it returns
get_status	Whether the (required) extension is connected + saved order/invoice counts per provider
list_orders	Compact order rows (number, date, title, total, item count), newest first; filter by date range, account, provider; paged
get_order	One order's full record, including the complete invoice when collected
search_orders	Free-text search across order numbers, titles, and item names, with matched items
spending_summary	Overall + per-month spending totals and order counts
export_orders	Full order records (summary + invoice) as JSON, paged
list_accounts	Walmart accounts with saved data (hashed keys only — never names/emails)
get_collection_progress	Live progress of an order-collection run
get_invoice_job	Live progress of a background invoice-fetch job

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):

Tool	What it does
start_collection	Starts collecting order history in a background browser tab (supports page limit, only-new-orders, order-type and date filters, fast mode)
stop_collection	Stops the running collection; already-saved orders are kept
collect_invoices	Fetches full invoices for saved orders (all missing, or a given list) in a background tab
cancel_invoice_job	Cancels the running invoice job after the in-flight order

Options

Flag	Env var	Default
--token	WALMART_INVOICE_MCP_TOKEN	— (required)	Pairing token from the extension's settings
--port	WALMART_INVOICE_MCP_PORT	8924	Localhost port the extension connects to (must match the extension's setting)
--timeout	—	15000	ms to wait for the extension to answer a call

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