LystBot: list app for AI agents

LystBot is a list app for AI agents and the people who use them. You and your assistant work on the same shared lists: ask it to add groceries or check off a task, then see the changes on your phone.

Connect through a local MCP server, the CLI or the REST API. All three use the same API key. The developer docs have the full reference.

npx lystbot add "Weekly Groceries" "500g cherry tomatoes; 3x avocados"

Connect your assistant

Install the LystBot app for iOS or Android, then copy your API key from Settings → AI Agents. Choose the connection your assistant supports. ChatGPT uses an app pairing code instead of an API key.

curl https://lystbot.com/api/v1/lists \
  -H "Authorization: Bearer YOUR_API_KEY"

Alexa

1. Enable the LystBot skill for Alexa.
2. Link it with a pairing code from the app. No API key, no Amazon account linking.
3. Say: "Alexa, tell LystBot to add milk to my shopping list."

CLI

Best for agents with a shell: OpenClaw, Grok Bot (on the bot's cloud computer), Devin, Aider, OpenCode and scripts. Install it with npm install -g lystbot, or put npx in front of every command as shown here.

# Log in once (the key is stored in ~/.lystbot/config.json)
npx lystbot login <API_KEY>

# Lists
npx lystbot lists                                   # all lists
npx lystbot show "Groceries"                        # one list with its items
npx lystbot create "Groceries" --type shopping --emoji "🛒"
npx lystbot delete "Old List" --force

# Items
npx lystbot add "Groceries" "Milk, Eggs, Bread"     # comma-separated
npx lystbot add "Groceries" "250g flour; 3x milk"   # amounts and units are parsed
npx lystbot check "Groceries" "Milk"
npx lystbot uncheck "Groceries" "Milk"
npx lystbot remove "Groceries" "Milk"

# Sections inside a list
npx lystbot categories "Groceries"
npx lystbot category add "Groceries" "Fruit"
npx lystbot add "Groceries" "Bananas" --category "Fruit"

# Reminders
npx lystbot reminders
npx lystbot remind "Take vitamins" --at "tomorrow 09:00" --timezone "Europe/Berlin"
npx lystbot reminder-delete <REMINDER_ID> --yes

# Sharing
npx lystbot share "Groceries"                       # get a share code
npx lystbot join <SHARE_CODE>

# Your name and emoji in shared lists
npx lystbot profile --name "TARS" --emoji "🤖"

# JSON output
npx lystbot show "Groceries" --json

All commands and flags: lystbot.com/docs/#cli

MCP server for your todo list

The CLI includes an MCP server. It runs locally over stdio (npx lystbot mcp), so it works with any MCP client that can start a local server. A remote OAuth MCP endpoint is also available at https://lystbot.com/api/v1/mcp. The remote endpoint uses OAuth rather than the local server's API key; client compatibility and available tools differ.

Log in first. Every setup below needs this:

npx lystbot login <API_KEY>

Claude Desktop

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows), then restart Claude Desktop:

{
  "mcpServers": {
    "lystbot": {
      "command": "npx",
      "args": ["lystbot", "mcp"]
    }
  }
}

Claude Code, Codex, Grok Build, OpenClaw

claude mcp add lystbot -- npx lystbot mcp     # Claude Code
codex mcp add lystbot -- npx lystbot mcp      # Codex
grok mcp add lystbot -- npx lystbot mcp       # Grok Build
openclaw mcp add lystbot -- npx lystbot mcp   # OpenClaw (or use the CLI directly)

Cursor, Devin Desktop, Antigravity, Cline

Add the same JSON as for Claude Desktop to the client's MCP config: .cursor/mcp.json for Cursor, ~/.config/devin/mcp_config.json for Devin Desktop (formerly Windsurf) and ~/.gemini/config/mcp_config.json for Antigravity. Cline has its own MCP settings screen.

Hermes Agent, Devin CLI, CrewAI

• Hermes Agent: add the server under mcp_servers in ~/.hermes/config.yaml with command npx and args ["lystbot", "mcp"].
• Devin CLI: register npx lystbot mcp with devin mcp add.
• CrewAI: connect over stdio with MCPServerAdapter, command npx, args ["lystbot", "mcp"]. The REST API works too.

Local stdio MCP tools (26)

• list_lists - Get all lists
• get_list - Get one list with its items
• create_list - Create a list
• delete_list - Delete a list
• add_items - Add items as plain text ("250g flour", "3x milk") or as {text, quantity?, unit?}
• check_item - Check off an item
• uncheck_item - Uncheck an item
• remove_item - Remove an item
• clear_checked - Remove all checked items from a list
• share_list - Get a share code for a list
• join_list - Join a shared list with a share code
• list_categories - List the sections of a list
• create_category - Create a section
• rename_category - Rename a section
• delete_category - Delete a section (its items move to Other)
• reorder_categories - Reorder sections
• move_item - Move an item to a section or to Other
• add_item_image - Attach an image to an item (local path or base64)
• add_item_url - Attach a link to an item
• list_item_attachments - List the attachments of an item
• delete_item_attachment - Delete an attachment
• list_reminders - Get all reminders
• get_reminder - Get one reminder
• create_reminder - Create a one-time or recurring reminder
• update_reminder - Change, enable or disable a reminder
• delete_reminder - Delete a reminder

Remote ChatGPT MCP tools (7)

list_lists, get_list, list_reminders, create_list, add_items, update_item, create_reminder. Use update_item to check or uncheck an item. Delete and sharing tools are unavailable. Setup: ChatGPT.

REST API

For Microsoft Copilot Studio (REST API tool from an OpenAPI description), the Gemini API and the xAI API (function calling), Manus, AutoGPT, Apple Shortcuts and your own code.

Base URL: https://lystbot.com/api/v1

Authentication: Authorization: Bearer <API_KEY>

Unless stated otherwise, request and response bodies use Content-Type: application/json. Image uploads use multipart/form-data; image and thumbnail GETs return authenticated binary image responses. New lists and items need a client-generated UUID v4 as id. For reminders, id is optional on creation, generated by the server when omitted or empty. A supplied non-empty ID must be a valid UUID.

# Lists
GET    /lists                       # all lists
POST   /lists                       # create a list
       {"id": "<uuid>", "title": "Groceries", "type": "shopping", "emoji": "🛒"}
       type: shopping | todo | packing | generic (default: generic)
GET    /lists/:id                   # one list with items, sections and members
PUT    /lists/:id                   # {"title": "...", "emoji": "...", "hide_completed": false}
DELETE /lists/:id

# Items
POST   /lists/:id/items             # add an item
       {"id": "<uuid>", "text": "Milk", "quantity": 2, "unit": "1l", "category_id": null}
PUT    /lists/:id/items/:itemId     # change any of: text, checked, quantity, unit, position, category_id
       {"checked": true}
DELETE /lists/:id/items/:itemId     # remove an item
DELETE /lists/:id/items/checked     # remove all checked items

# Sharing
POST   /lists/:id/share             # returns {"share_code": "ABC123"}
POST   /lists/join                  # {"code": "ABC123"}
POST   /lists/:id/leave

# Reminders
GET    /reminders
POST   /reminders
       {"id": "<uuid>", "title": "Take vitamins", "scheduled_at": "2027-01-15 09:00",
        "timezone": "Europe/Berlin", "repeat": "none", "is_enabled": true}
       repeat: none | daily | weekly | biweekly | monthly | yearly
GET    /reminders/:id
PUT    /reminders/:id
DELETE /reminders/:id

# Your name and emoji in shared lists
PATCH  /agents/me                   # {"name": "TARS", "signature_emoji": "🤖"}

Rules: CLI and local MCP counts are integers in 1..99. REST quantity handling depends on unit: creation validates the applicable range, while updates clamp values to it. Do not infer REST limits from CLI limits. Weights and volumes go into unit, so 250 g of flour is "unit": "250g", not "quantity": 250. A list holds up to 300 items. Items without category_id go to the section Other. The API accepts one-time reminders ("repeat": "none") with a timestamp in the past. Replace scheduled_at with a future local date and time in the specified timezone.

Errors look like {"error": "not_found", "message": "..."}. Sections, attachments and favorites are in the full reference: lystbot.com/docs

System prompt block

Copy this into your agent's system prompt or context:

You can manage the user's LystBot lists through the REST API.
Base URL: https://lystbot.com/api/v1
Auth header: Authorization: Bearer <API_KEY>
New lists and items need a client-generated UUID v4 as "id".

Endpoints:
- GET    /lists                    - All lists
- POST   /lists                    - Create a list  {"id": "<uuid>", "title": "...", "type": "shopping|todo|packing|generic"}
- GET    /lists/:id                - One list with its items
- POST   /lists/:id/items          - Add an item    {"id": "<uuid>", "text": "...", "quantity": 1-99 (1-9999 with unit), "unit": "..."}
- PUT    /lists/:id/items/:itemId  - Change an item {"checked": true} or {"text": "..."}
- DELETE /lists/:id/items/:itemId  - Remove an item

When the user asks to add something to a list, add it.
When the user asks what's on a list, read the list first.
Tell the user what you changed.

What LystBot is

• Mobile app for iOS and Android. Free during launch, no account needed.
• Made for agents: the CLI, the MCP server and the REST API all use the same API key.
• Shared lists: family members and agents work on the same list. Changes show up on every phone right away.
• Sections inside a list, like Produce or Dairy. Items without a section go to Other.
• Reminders, one-time or recurring, with push notifications.
• Amounts: "2x milk" or "500g flour" is split into amount, unit and item name.

Supported clients

• ChatGPT (OpenAI): LystBot connection through remote OAuth MCP; pair using a code from Settings → ChatGPT
• Claude Desktop, Claude Code (Anthropic): MCP
• Codex (OpenAI): MCP
• Cursor: MCP
• Devin Desktop (formerly Windsurf), Devin CLI (Cognition): MCP
• Grok Build (xAI): MCP
• Grok Bot (xAI): CLI on the bot's cloud computer
• Grok (xAI API): REST API via function calling
• Antigravity (Google): MCP
• Gemini API (Google): REST API via function calling
• Copilot Studio (Microsoft): REST API tool from an OpenAPI description
• OpenClaw: CLI or MCP
• Hermes Agent (Nous Research): MCP
• CrewAI: MCP or REST API
• GitHub Copilot, Cline: MCP
• OpenCode: CLI or MCP
• Aider: CLI
• AutoGPT, Manus, Apple Shortcuts: REST API
• Siri: native Siri actions; optional REST shortcuts
• Amazon Alexa: official LystBot skill
• Any other agent that can run a shell command or call an HTTP API

List types

shopping, todo, packing, generic

More ways to use your lists

• Connect Claude to your grocery list with MCP
• Let an AI agent manage your lists
• Use a list app with an API

Links

• Website: https://lystbot.com
• Docs: https://lystbot.com/docs/
• GitHub: https://github.com/TourAround/LystBot
• npm: https://www.npmjs.com/package/lystbot
• Privacy Policy: Privacy Policy
• Legal Notice: Imprint

© 2026 TourAround UG (haftungsbeschränkt)