# walmart-invoice-mcp

[![npm](https://img.shields.io/npm/v/walmart-invoice-mcp)](https://www.npmjs.com/package/walmart-invoice-mcp)

MCP server for the [Walmart Invoice Exporter](https://github.com/hppanpaliya/Walmart-Invoice-Exporter) browser extension ([website](https://github.harsh.al/Walmart-Invoice-Exporter/)). It lets Claude Code, Claude Desktop, and any other [Model Context Protocol](https://modelcontextprotocol.io) 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](https://github.com/hppanpaliya/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](https://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](https://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`):

   ```json
   {
     "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`](https://pnpm.io/settings#minimumreleaseage) set to 14 days.

## Development

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

## License

MIT