{
  "markdown": "# listonic-mcp\n\n<!-- mcp-name: io.github.ArturLys/listonic-mcp -->\n\n[![PyPI](https://img.shields.io/pypi/v/listonic-mcp)](https://pypi.org/project/listonic-mcp/)\n[![CI](https://github.com/ArturLys/listonic-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/ArturLys/listonic-mcp/actions/workflows/ci.yml)\n![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)\n![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)\n\nAn [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that gives AI agents — Claude, Cursor, or any MCP client — hands on your real [Listonic](https://listonic.com/) grocery list. Read it, add to it, check things off, across every device Listonic syncs to.\n\nThe obvious win: **meal planning that ends in a shopping list.** Ask your agent to plan the week's dinners, and the missing ingredients land straight on the list on your phone — quantities and all. Or paste a recipe and say \"add what I don't have\": the server tells the agent which items are checked (already at home) and which aren't.\n\n```\nYou:   plan me 3 cheap high-protein dinners and put the ingredients on my list\nAgent: [reads your list — sees you already have rice, eggs, frozen spinach]\n       [adds: 1 kg chicken thighs, 400 g lentils, greek yogurt ×2, ...]\n```\n\n> **Unofficial.** Not affiliated with Listonic. Built on their web app's API (reverse-engineered — fully documented in [API.md](API.md)). It may break if Listonic changes their API.\n\n## Install\n\nRequires **Python 3.10+** and a Listonic account (free):\n\n```bash\npip install listonic-mcp\n```\n\n## Add to your agent\n\nPoint `command` at `listonic-mcp` and pass your Listonic login:\n\n```json\n{\n  \"mcpServers\": {\n    \"listonic\": {\n      \"command\": \"listonic-mcp\",\n      \"env\": {\n        \"LISTONIC_EMAIL\": \"you@example.com\",\n        \"LISTONIC_PASSWORD\": \"your-listonic-password\"\n      }\n    }\n  }\n}\n```\n\nThe same values can be passed as `--email` / `--password` args instead — whichever your client makes easier.\n\n<details>\n<summary>Claude Code</summary>\n\n```bash\nclaude mcp add listonic -e LISTONIC_EMAIL=you@example.com -e LISTONIC_PASSWORD=your-password -- listonic-mcp\n```\n\n</details>\n\n<details>\n<summary>Cursor</summary>\n\n`Cursor Settings` → `MCP` → `New MCP Server`, paste the JSON config above.\n\n</details>\n\n<details>\n<summary>Google Antigravity</summary>\n\nAdd the JSON config above to `.gemini/antigravity/mcp_config.json`.\n\n</details>\n\nThen just ask:\n\n```\nWhat's on my grocery list? Check off the milk, I just bought it.\n```\n\n### Launch params\n\n| Param        | Env var             | Default        | What it does                                        |\n| ------------ | ------------------- | -------------- | --------------------------------------------------- |\n| `--email`    | `LISTONIC_EMAIL`    | —              | Listonic account email (required).                  |\n| `--password` | `LISTONIC_PASSWORD` | —              | Listonic account password (required).               |\n| `--list-id`  | `LISTONIC_LIST_ID`  | first list     | Pin a default list; see `get_lists` for the ids.    |\n\n## Tools\n\n| Tool           | What it does                                                              |\n| -------------- | ------------------------------------------------------------------------- |\n| `get_lists`    | All your shopping lists with their ids.                                    |\n| `get_items`    | Items on a list — checked (already have) vs unchecked (to buy).            |\n| `add_items`    | Add one or many items in a single call (name, quantity, unit).             |\n| `edit_items`   | Check/uncheck, rename, or re-quantity items — batched.                     |\n| `delete_items` | Remove items entirely.                                                     |\n\nEvery tool takes an optional `list_id`, so multiple lists (\"weekend BBQ\", \"pharmacy\") work naturally.\n\n## Good to know\n\n- **Your password goes to Listonic only.** The server logs in against `api.listonic.com` directly and talks to nothing else — no telemetry, nothing stored beyond an in-memory session token (auto-refreshed when it expires).\n- The client id/secret in the source are Listonic's own web-app credentials, embedded in their public JS bundle and shared by every web user — they are not personal secrets.\n- The full reverse-engineered API is documented in [API.md](API.md) — lists, items, categories, account endpoints — if you want to extend the server.\n\n## Make it yours\n\nA single readable file with no framework magic. Fork it and edit anything — add price tracking, category sorting, a recipe parser. Run from source:\n\n```bash\ngit clone https://github.com/ArturLys/listonic-mcp.git\ncd listonic-mcp\npip install -e .\nlistonic-mcp --email you@example.com --password your-password\n```\n\n## Credits\n\n- [Listonic](https://listonic.com/) — the shopping list app this talks to. Go pay them for premium if you live off it.\n\n## License\n\nMIT\n",
  "bytes": 4929,
  "sha": "62b61ce3dea73342856a0c8d3182052c68b4225937d9b82709343cd4b4c7e812",
  "repo_slug": "arturlys/listonic-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_arturlys_listonic_mcp_a4c5890d/readme"
}