Skip to main content
Glama

ica-mcp

CI

An MCP server for ICA — Sweden's largest grocery chain — that lets AI agents (Claude, or any Model Context Protocol client) read and edit your ICA shopping lists in natural language:

"What's on my shopping list?" · "Add coffee and bananas to the Willys list" · "Check off milk" · "Clear the checked items"

ICA has no official public API. This server talks to the same private backend the ICA mobile app uses, authenticating with your personnummer + password (no BankID required for accounts that support password login).

⚠️ Unofficial & unaffiliated. This project is not affiliated with, endorsed by, or supported by ICA. It relies on a private, undocumented API that can change or break at any time, and using it may be against ICA's terms of service. Use at your own risk, for personal use only.

Tools

Tool

What it does

list_shopping_lists

All your lists + how many items remain/checked

view_shopping_list

Contents of a list (by name; defaults to your primary list), with each item's category

add_items

Add one or more free-text items to a list, optionally with a category for the whole call or per item (otherwise ICA picks one from the name)

check_off / uncheck

Mark an item bought / undo

remove_item

Remove an item entirely

clear_checked

Remove all checked items (tidy up after shopping)

create_shopping_list / delete_shopping_list

Create / delete a list

list_saved_recipes / get_recipe

Your favourite recipes; one recipe's ingredients + steps

random_recipes

Random recipes for inspiration

add_recipe_to_shopping_list

Add a recipe's ingredients to a list as free-text items

list_stores / get_offers

Your favourite stores; current offers for a store

get_bonus

Your ICA bonus / Stammis balance

get_product

Look up a product by barcode (EAN/GTIN)

add_product_to_shopping_list

Look up a barcode and add the product's name to a list

offers_on_my_list

Which items on your list are on sale at a store

add_recipes_to_shopping_list

Merge several recipes' ingredients onto one list

plan_dinners

Random weekly menu → one aggregated shopping list

Lists, items and stores are referenced by name, so an agent can act on natural language. Omitting a list/store name targets your primary one (the Handla list / your first favourite store).

Related MCP server: Bring! Shopping MCP Server

Requirements

  • Python 3.10+

  • A Swedish egress IP. ICA's API gateway (apimgw-pub.ica.se) returns HTTP 451 to non-Swedish IPs. Run this on a machine/network in Sweden — a US/DE VPS will not work.

  • An ICA account that logs in with personnummer + password (accounts locked to BankID-only are not supported).

Setup

Everything is one ica-mcp command with four subcommands:

Command

What it does

ica-mcp login

Log in once (personnummer + password) and cache the session

ica-mcp register

Register the server with Claude Code (--scope user)

ica-mcp status

Show the cache location + whether the session is valid (no login)

ica-mcp serve

Run the MCP server over stdio — what your client launches

1. Install

The quickest path uses uv — one command, identical on Windows, macOS and Linux:

# (only if you don't have uv yet)
#   Windows:      winget install --id=astral-sh.uv -e
#   macOS/Linux:  curl -LsSf https://astral.sh/uv/install.sh | sh

uv tool install ica-mcp
uv tool update-shell      # puts `ica-mcp` on PATH — then open a NEW terminal

For the latest unreleased code use the repo instead of PyPI: uv tool install git+https://github.com/kanylbullen/ica-mcp

git clone https://github.com/kanylbullen/ica-mcp.git
cd ica-mcp
python3 -m venv .venv
.venv\Scripts\pip install .      # Windows
.venv/bin/pip install .          # macOS / Linux

Then use the venv's ica-mcp in place of the bare command below: .venv\Scripts\ica-mcp.exe (Windows) or .venv/bin/ica-mcp (macOS/Linux).

2. Log in (once)

ica-mcp login          # prompts for personnummer + password (hidden)

On success it prints your name and lists and caches the session (OAuth client + tokens) in a per-user state dir — %LOCALAPPDATA%\ica-mcp (Windows), ~/.local/state/ica-mcp (Linux), ~/Library/Application Support/ica-mcp (macOS). The short-lived access token (~15 min) is auto-refreshed via the long-lived refresh token, so you normally log in only once. Verify anytime:

ica-mcp status         # cache path + session validity, without logging in

3. Register with your MCP client

Claude Code — let the CLI do it (writes at user scope, resolving the right path):

ica-mcp register

Registering at --scope user sidesteps a Windows drive-letter project-key quirk. If the claude CLI isn't found, register prints a ready-to-paste mcp.json. The equivalent manual command is:

claude mcp add ica --scope user -- ica-mcp serve

Any other MCP client (mcp.json):

{
  "mcpServers": {
    "ica": {
      "command": "ica-mcp",
      "args": ["serve"]
    }
  }
}

If ica-mcp isn't on PATH, use the absolute path uv printed at install, or python -m ica_mcp serve.

Restart your MCP client and the tools appear. The server reads the cached session, so it needs no credentials in its environment. If the refresh token ever expires, re-run ica-mcp login — or set ICA_USER / ICA_PASS (see .env.example) so serve can re-authenticate unattended. Relocate the cache with ICA_STATE_FILE.

How authentication works

ICA migrated (around 2024) from a simple Basic-auth API to an OAuth 2.0 / OIDC flow backed by a Curity Identity Server at ims.icagruppen.se, with the data API behind an F5 gateway at apimgw-pub.ica.se. The flow is:

  1. bootstrap client-credentials token (scope=dcr)

  2. dynamic client registration (POST /register) → per-install client

  3. PKCE authorize → HTML login form

  4. POST /authn/authenticate/IcaCustomers with personnummer + password

  5. exchange the resulting code for a Bearer access/refresh token

The auth flow is a standalone port of the excellent LazyTarget/ha-ica-todo Home Assistant integration — full credit for reverse-engineering the current flow. The hardcoded DCR bootstrap client id/secret are ICA app constants (also public in that project), not user secrets.

Security & privacy

  • Tokens are cached in a per-user state dir (see Log in), outside the repo, chmod 0600 on POSIX. On Windows that only toggles the read-only bit, so the file is not OS-ACL-protected there — treat the machine account as the trust boundary. Set ICA_STATE_FILE to relocate the cache.

  • No keyring dependency by design. The Swedish-egress requirement pushes many users onto headless homelab/VPS boxes that lack a Secret Service / Credential Manager; a portable 0600 file is the deliberate choice.

  • Nothing is logged to stdout (stdout is reserved for the MCP protocol — logs go to stderr).

  • This server can modify your real ICA account (add/remove items, delete lists). Write operations were validated against throwaway lists during development.

Roadmap

Done: shopping lists (phase 1); recipes + offers + bonus (phase 2); product / barcode lookup (phase 3); smart flows (phase 4 — offers_on_my_list, add_recipes_to_shopping_list, plan_dinners).

Planned next, on the same auth:

  • Recipe search by phrase — deferred: recipes/search & searchwithfilters return HTTP 500 for every GET param shape tried (and 405 on POST), so the real request shape needs capturing from live app traffic.

  • Personal offers across stores

  • Unit tests + CI, and a PyPI release

Credits

Development

pip install -e ".[test]"
pytest

Tests (tests/) cover the pure helpers only — ingredient aggregation, offer/recipe formatting, list/row matching, PKCE and redirect/form parsing. The live ICA API can't run in CI (it needs a Swedish IP and a login), so it's exercised manually. CI runs the suite on Python 3.10–3.13.

License

MIT — see LICENSE.

Available Tools

21 tools
add_itemsA

Lägg till en eller flera varor (fri text, t.ex. 'mjölk', '2 kg potatis') på en inköpslista. Utelämna list_name för den primära listan.

Kategori är valfri och anges med namnen från ICA-appen (t.ex. 'Mejeri', 'Frukt & Grönt', 'Städ & disk', 'Djur'). Utelämnad väljer ICA kategori utifrån varans namn, vilket räcker för vanliga matvaror. category gäller alla varor i anropet; en vara kan också ges som {"name": ..., "category": ...} med egen kategori, så att en blandad korg går i ett anrop.

Inputs: items (required), category, list_name. Returns: result

add_product_to_shopping_listA

Slå upp en streckkod (EAN/GTIN) och lägg produktens namn på en lista. Utelämna list_name för primärlistan.

Inputs: ean (required), list_name. Returns: result

add_recipes_to_shopping_listA

Lägg ingredienserna från FLERA recept på en lista, ihopslagna (samma vara + enhet summeras). Utelämna list_name för primärlistan.

Inputs: recipe_ids (required), list_name. Returns: result

add_recipe_to_shopping_listA

Lägg alla ingredienser från ett recept som varor på en inköpslista (fri text, t.ex. '8 dl mjölk'). Utelämna list_name för primärlistan.

Inputs: recipe_id (required), list_name. Returns: result

check_offC

Bocka av en vara (markera som köpt/klar) på en lista.

Inputs: item (required), list_name. Returns: result

clear_checkedB

Ta bort alla avbockade varor från en lista (rensa upp efter handling).

Inputs: list_name. Returns: result

create_shopping_listC

Skapa en ny inköpslista med angiven titel.

Inputs: title (required). Returns: result

delete_shopping_listB

Radera en hel inköpslista (kräver att du anger listnamnet explicit).

Inputs: list_name (required). Returns: result

get_bonusA

Visa din ICA-bonus/Stammis: kupongvärde, aktiva kuponger och rabatt hittills.

Inputs: no named parameters.

get_offersA

Hämta aktuella erbjudanden för en butik. store_name matchas mot dina favoritbutiker (utelämna för din primära butik). query filtrerar på varunamn/märke/kategori (t.ex. 'kaffe').

Inputs: limit, query, store_name.

get_productA

Slå upp en produkt via streckkod (EAN/GTIN). Returnerar namn + artikelgrupp, eller found=False om koden inte finns.

Inputs: ean (required).

get_recipeB

Hämta ett recept: titel, tid, portioner, ingredienser (fri text) och tillagningssteg.

Inputs: recipe_id (required).

list_saved_recipesA

Lista dina favoritmarkerade recept (senast tillagda först). Hämtar detaljer per recept, så håll limit lågt (standard 12).

Inputs: limit.

list_shopping_listsA

Lista alla dina ICA-inköpslistor med antal varor kvar och avbockade. Den första listan är din primära ('Handla') och används som standard när inget listnamn anges i andra verktyg.

Inputs: no named parameters. Returns: result

list_storesA

Lista dina favoritbutiker (id, namn, ort). Den första är standardbutik för erbjudanden.

Inputs: no named parameters. Returns: result

offers_on_my_listA

Korsa din inköpslista mot en butiks aktuella erbjudanden — visar vilka ännu ej avbockade varor på listan som är på extrapris. Utelämna list_name/store_name för primärlistan / din primära butik.

Inputs: list_name, store_name.

plan_dinnersA

Planera veckans middagar: hämtar count slumprecept (1–10), slår ihop deras ingredienser och lägger på en lista (skapar 'Veckans middagar' om list_name utelämnas). Returnerar menyn.

Inputs: count, list_name.

random_recipesA

Hämta slumpmässiga recept för inspiration (count 1–10).

Inputs: count. Returns: result

remove_itemB

Ta bort en vara helt från en lista (inte samma som att bocka av).

Inputs: item (required), list_name. Returns: result

uncheckC

Ångra avbockning av en vara (markera som ej köpt igen).

Inputs: item (required), list_name. Returns: result

view_shopping_listA

Visa innehållet i en inköpslista. list_name matchas mot listans titel (utelämna för den primära listan). Returnerar varor uppdelat i kvar/avbockade.

Inputs: list_name.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.3/5.0

    Scored across 21 tools

    Disambiguation3/5

    Most tools map to a clear resource+action, but `add_recipe_to_shopping_list` and `add_recipes_to_shopping_list` differ by a single character while doing different things (one recipe vs. several merged), which is a real misselection risk. `plan_dinners` also overlaps with the recipe-adding tools, and `add_items`/`add_product_to_shopping_list`/`add_recipe_to_shopping_list` all ultimately append to a list, distinguished only by source.

    Naming Consistency3/5

    All names are snake_case, which is good, but the verb pattern is inconsistent: most follow verb_noun (view_shopping_list, create_shopping_list, get_offers), yet several are bare verbs or noun phrases (check_off, uncheck, random_recipes, offers_on_my_list). The singular/plural pair breaks predictability further.

    Tool Count4/5

    21 tools sits at the heavy end, but they span four legitimately distinct sub-domains (list management, recipes, stores/offers, bonus/product lookup) plus compound convenience tools, so each earns a place. The count is defensible, though a couple of recipe-to-list variants could be collapsed into one parameterized tool.

    Completeness4/5

    Shopping list lifecycle is fully covered (create, list, view, add, remove, check off, uncheck, clear checked, delete), and recipes, offers, stores, and barcode lookup round it out. Minor gaps remain: no recipe search by keyword, no favorite/save toggle for recipes, no store add/remove, and no edit of item quantity or text.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with Mathem.se, a Swedish online grocery store, allowing users to search for ingredients, add items to their shopping basket, and manage recipes through natural language.
      4
      2
      -
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables agentic grocery shopping on Oda (Norway) and Mathem (Sweden) platforms through an MCP-compatible interface. Users can search for products, manage their shopping cart, and access order history using natural language commands.
      1
      MIT
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to manage shopping lists and items (create, edit, delete, mark as purchased) via integration with a backend API.
      8
      -