ica-mcp
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).
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:
- bootstrap client-credentials token (
scope=dcr)
- dynamic client registration (
POST /register) → per-install client
- PKCE authorize → HTML login form
POST /authn/authenticate/IcaCustomers with personnummer + password- 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.
