Costco
by thehesiodcommunityv0.1.2
1
An MCP server that provides access to Costco warehouse receipts, online orders, and product lookups through Costco's internal GraphQL APIs. It also lets you check auth status and save per-account OAuth refresh tokens for multiple accounts.
From the registry: MCP server for Costco warehouse receipts and online orders
Install & configure
Prerequisites
- requiredInstall uv/uvxInstall the Python package runner `uv` so you can launch the MCP server with `uvx`.https://docs.astral.sh/uv/
- optionalOptional: Install Chrome or Chromium for semi-automated authenticationNeeded only if you want to use the recommended semi-automated auth flow that launches a browser and extracts the Costco refresh token via chrome-devtools-mcp.
- requiredAuthenticate with Costco and save a refresh tokenYou must obtain a Costco OAuth2 refresh token from a logged-in browser session and register it with the server. The README recommends the semi-automated browser flow, or a manual fallback using `costco-mcp-server --save-token <account> <REFRESH_TOKEN>`. The token is stored locally under `~/.costco-mcp/`.
$ uvx costco-mcp-server --save-token <account-name> <refresh-token>
Install in your client
Paste into the AI you're chatting with — it will figure out the rest
Please install the `costco` MCP server into my current AI client (that's you).
Required prerequisites (do these first if not already done):
- **Install uv/uvx** — Install the Python package runner `uv` so you can launch the MCP server with `uvx`. (https://docs.astral.sh/uv/)
- **Authenticate with Costco and save a refresh token** — You must obtain a Costco OAuth2 refresh token from a logged-in browser session and register it with the server. The README recommends the semi-automated browser flow, or a manual fallback using `costco-mcp-server --save-token <account> <REFRESH_TOKEN>`. The token is stored locally under `~/.costco-mcp/`. Run: `uvx costco-mcp-server --save-token <account-name> <refresh-token>`
Optional prerequisites:
- Optional: Install Chrome or Chromium for semi-automated authentication — Needed only if you want to use the recommended semi-automated auth flow that launches a browser and extracts the Costco refresh token via chrome-devtools-mcp.
Canonical MCP server config (stdio transport):
- command: `uvx`
- args: ["costco-mcp-server"]
- optional environment variables:
- `COSTCO_AUTH_PORT`: Override the debugger port used by `costco-auth-browser` during the optional semi-automated authentication flow. (example: `<port>`)
Note: Prefer the published PyPI path `uvx costco-mcp-server` over the Git URL variant. The MCP server itself does not require environment variables for normal operation; authentication is handled by saving refresh tokens locally rather than supplying secrets in MCP config. The README also documents an optional helper browser command (`costco-auth-browser`) and a separate optional MCP server (`chrome-devtools-mcp`) to automate token extraction, but those are not part of the Costco server's own canonical MCP config.
Add this MCP server to my current client's config in the correct format for you. If you need secrets or credentials I haven't provided, ASK me — do not invent values or leave raw placeholders. After adding it, tell me how to verify the server is connected.Note: Prefer the published PyPI path `uvx costco-mcp-server` over the Git URL variant. The MCP server itself does not require environment variables for normal operation; authentication is handled by saving refresh tokens locally rather than supplying secrets in MCP config. The README also documents an optional helper browser command (`costco-auth-browser`) and a separate optional MCP server (`chrome-devtools-mcp`) to automate token extraction, but those are not part of the Costco server's own canonical MCP config.
Tools (7)
list_warehouse_receipts
Lists in-store receipts for a date range, including barcode, warehouse, and total.
get_receipt_detail
Fetches full itemized details for a receipt by barcode.
get_all_receipt_details
Bulk fetches full details for every receipt in a date range.
list_online_orders
Lists Costco.com orders for a date range, including order number, status, items, and totals.
lookup_products
Resolves item numbers to full product names and department information using a local cache.
check_auth_status
Reports token freshness and lists configured accounts.
save_refresh_token
Registers or updates an account's refresh token.
Environment variables
COSTCO_AUTH_PORTOverrides the debugger port used by the auth browser for the semi-automated token extraction flow.Packages
costco-mcp-server
pypiv0.1.2transport: stdio
Details
- Language
- Python
- License
- MIT
- Released
- Apr 19, 2026
- Last commit
- Apr 19, 2026
- Registry name
- io.github.thehesiod/costco