About listonic-mcp
listonic-mcp is an unofficial MCP server that lets AI agents read and edit a user's Listonic grocery lists. It supports multiple lists and item quantities, using Listonic's web app API directly.
Key features
- 01List available shopping lists
- 02Read checked and unchecked items
- 03Add items with quantities and units
- 04Edit, check off, or rename items
- 05Delete list items
Use cases
- 01Turn meal plans into grocery lists
- 02Check off groceries after shopping
- 03Update quantities across multiple lists
MCP support
Exposes Listonic list and item operations as MCP tools for AI clients, using the user's Listonic account credentials.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
uvx listonic-mcpLISTONIC_EMAILListonic account emailLISTONIC_PASSWORDSecretListonic account passwordLISTONIC_LIST_IDOptional: pin a default list id (otherwise the account's first list is used)Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
5Saved tool list · updated 3w ago
This tool takes no parameters.
Details
From the project READMElistonic-mcp
An MCP (Model Context Protocol) server that gives AI agents — Claude, Cursor, or any MCP client — hands on your real Listonic grocery list. Read it, add to it, check things off, across every device Listonic syncs to.
The 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.
You: plan me 3 cheap high-protein dinners and put the ingredients on my list
Agent: [reads your list — sees you already have rice, eggs, frozen spinach]
[adds: 1 kg chicken thighs, 400 g lentils, greek yogurt ×2, ...]
Unofficial. Not affiliated with Listonic. Built on their web app's API (reverse-engineered — fully documented in API.md). It may break if Listonic changes their API.
Install
Requires Python 3.10+ and a Listonic account (free):
pip install listonic-mcp
Add to your agent
Point command at listonic-mcp and pass your Listonic login:
{
"mcpServers": {
"listonic": {
"command": "listonic-mcp",
"env": {
"LISTONIC_EMAIL": "[email protected]",
"LISTONIC_PASSWORD": "your-listonic-password"
}
}
}
}
The same values can be passed as --email / --password args instead — whichever your client makes easier.
Claude Code
claude mcp add listonic -e [email protected] -e LISTONIC_PASSWORD=your-password -- listonic-mcp
Cursor
Cursor Settings → MCP → New MCP Server, paste the JSON config above.
Google Antigravity
Add the JSON config above to .gemini/antigravity/mcp_config.json.
Then just ask:
What's on my grocery list? Check off the milk, I just bought it.
Launch params
| Param | Env var | Default | What it does |
|---|---|---|---|
--email | LISTONIC_EMAIL | — | Listonic account email (required). |
--password | LISTONIC_PASSWORD | — | Listonic account password (required). |
--list-id | LISTONIC_LIST_ID | first list | Pin a default list; see get_lists for the ids. |
Tools
| Tool | What it does |
|---|---|
get_lists | All your shopping lists with their ids. |
get_items | Items on a list — checked (already have) vs unchecked (to buy). |
add_items | Add one or many items in a single call (name, quantity, unit). |
edit_items | Check/uncheck, rename, or re-quantity items — batched. |
delete_items | Remove items entirely. |
Every tool takes an optional list_id, so multiple lists ("weekend BBQ", "pharmacy") work naturally.
Good to know
- Your password goes to Listonic only. The server logs in against
api.listonic.comdirectly and talks to nothing else — no telemetry, nothing stored beyond an in-memory session token (auto-refreshed when it expires). - 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.
- The full reverse-engineered API is documented in API.md — lists, items, categories, account endpoints — if you want to extend the server.
Make it yours
A single readable file with no framework magic. Fork it and edit anything — add price tracking, category sorting, a recipe parser. Run from source:
git clone https://github.com/ArturLys/listonic-mcp.git
cd listonic-mcp
pip install -e .
listonic-mcp --email [email protected] --password your-password
Credits
- Listonic — the shopping list app this talks to. Go pay them for premium if you live off it.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.