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

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:

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

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

• Auth flow ported from LazyTarget/ha-ica-todo
• Historical API reference: svendahlstrand/ica-api (documents the now-defunct handla.api.ica.se backend)

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.