LystBot

MCP server Claude Code setup: a real list with LystBot

To connect the LystBot MCP server to Claude Code, first run npx lystbot login YOUR_API_KEY. Then register the local stdio server with claude mcp add lystbot -- npx lystbot mcp so Claude can read and change the lists on your phone.

Illustration of a developer at a terminal with a robot connecting to a checklist
Step Command Purpose
Authenticate npx lystbot login YOUR_API_KEY Store the key locally
Read npx lystbot lists Compare lists with the phone app
Register claude mcp add lystbot -- npx lystbot mcp Connect Claude Code to the local server

LystBot gives Claude access to the same lists you use on your phone. The server is included in the CLI, starts locally over stdio and exposes 26 tools. There is no hosted MCP URL. Those details matter when you choose a client and when you troubleshoot a connection.

This walkthrough uses the setup commands from LystBot's agent page and developer reference. The first goal is deliberately small: authenticate, read a known list, make one change and verify it in the app. A large prompt can wait until that works.

Decide which tasks belong in a shared list

A Claude todo list can hold the real-world follow-ups that otherwise get buried during a coding session. Call the electrician. Buy printer paper. Pack an adapter before leaving for a conference. The assistant can help phrase those items, but the saved list is where you and other people act on them.

For the first test, pick harmless content that you can recognize immediately. Avoid a production checklist, an urgent reminder or a household list someone is actively shopping from. You want to learn whether the connection works without wondering whether an unexpected change came from your test or another person.

Also decide what success looks like. Seeing a server name in a client is only a connection check. Seeing the intended item in the intended list on your phone proves the useful part of this workflow. Checking that no duplicate or wrong-list item appeared is the other half of the test.

Step 1: copy your LystBot API key

Install the mobile app, open Settings and choose AI Agents. Copy the API key. The CLI, REST API and MCP server use that same credential, so you don't need to invent a separate login method for each interface.

The terminal needs npx available. If it isn't available, resolve that before trying the registration command. The setup shown here also assumes you already have Claude Code available. This article covers LystBot's connection, not installation of the assistant itself.

Keep the key private. In screenshots, issue reports and shared examples, leave YOUR_API_KEY as a placeholder. The actual value belongs in your local login command. Don't put it into a project README just because the rest of the setup is convenient to copy.

Step 2: authenticate and read through the CLI

Run these documented commands, replacing the placeholder with your own key:

npx lystbot login YOUR_API_KEY
npx lystbot lists

The CLI stores the key in ~/.lystbot/config.json. Read the returned list names and compare them with the mobile app. If the result is wrong or authentication fails, fix that before registering the server. Keeping this check outside the assistant makes the failure easier to isolate.

To prepare a new list with the reference example, use:

npx lystbot create "Groceries" --type shopping --emoji "🛒"
npx lystbot add "Groceries" "Milk, Eggs, Bread"
npx lystbot show "Groceries"

If you already have a grocery list with that name, read it first rather than blindly repeating the creation step. Open the list on your phone and inspect its contents. These commands are also useful on their own: the terminal workflow guide covers using the CLI without any conversational layer.

Step 3: register the local server

Use the exact Claude Code MCP registration command documented by LystBot:

claude mcp add lystbot -- npx lystbot mcp

The command being registered is npx lystbot mcp. The client starts that local process and communicates with it over stdio. You don't supply a URL or run a separate hosted service for this setup.

Authenticate in the environment where the server will run. A login in one home directory doesn't prove that a process started under a different user has the same configuration. If you use an isolated development environment, check where the process starts and where the CLI saved the key. Keep the explanation this concrete before changing configuration at random.

For clients that accept only remote MCP URLs, this local server isn't a direct fit. LystBot documents a REST API for HTTP access instead. That limitation is easier to discover now than after spending an hour looking for a server URL that isn't part of the product.

Step 4: read before writing

Start with a request such as: "Read my LystBot lists and show their names. Don't change anything." Then ask Claude to read the specific list you verified earlier. Compare its answer with the CLI output and your phone.

The relevant tool names are list_lists and get_list. The server also includes add_items and check_item for changes. Knowing those names helps you distinguish a real tool result from a conversational answer that merely repeats what you typed.

For a first write, ask: "Add coffee to the Groceries list, then read that list back." This is an example request, not a guaranteed transcript. Inspect the resulting tool activity and the saved item. If Claude reports that the tool failed or cannot access the list, treat the task as unfinished.

If the target is ambiguous, stop the write and choose the right list first. A plausible assistant response doesn't resolve ambiguity. You can read the lists directly from the terminal again while you investigate.

Step 5: verify a reversible change

Find coffee in the phone app. Confirm that it is on the intended list and appears only as expected. If the item already existed, inspect the actual change before trying again; repeating the same request isn't a reliable repair for an uncertain result.

For a check-off test, choose a harmless test item, ask Claude to check it, then inspect the checked state in the app. LystBot also exposes uncheck_item, so you can reverse a test check. Avoid testing deletion just to prove the connection: reading and a small reversible item change already demonstrate useful access.

Only after those checks should you try a longer request. For a recipe, ask Claude to show the proposed ingredients before adding them. Review quantities and pantry assumptions yourself. The assistant may help draft the list, but it can't infer what is already in your kitchen from a successful MCP connection.

Use the other tools when the job needs them

The 26-tool reference includes sharing, categories, item attachments and reminders. share_list produces a share code; join_list joins through a code. Category tools organize sections within a list. Reminder tools include reading, creating, updating and deleting reminders.

Use the full reference before expanding the workflow. A reminder needs a sensible time and timezone; a shared list needs the right people. Neither decision should be guessed just because the server exposes a tool for it.

For household examples, the Claude grocery walkthrough covers a related use case. For deciding whether an API, CLI or MCP connection fits a particular job, read the programmable list guide.

When the connection fails, keep the checks narrow

First, run npx lystbot lists in the server's environment. If that fails, concentrate on CLI availability and authentication. If it works, inspect the registered command and confirm it launches npx lystbot mcp. Don't replace stdio configuration with a guessed URL.

If reads work but a change looks wrong, inspect the target list and item before retrying. Record the failed operation without sharing the key. A connection problem, a missing credential and a request against the wrong list need different fixes. Repeating a broad prompt hides those differences.

FAQ

Is this a hosted server I can paste into a URL field?

No. LystBot's documented MCP server is a local stdio process started with npx lystbot mcp. Use the REST interface when your integration requires HTTP.

Do I need separate credentials for the CLI and MCP?

No. Both use the LystBot API key. Authenticate locally before the client starts the server and verify the CLI can read your lists in that environment.

How many tools does the server have?

The current reference lists 26. Start with list_lists and get_list, then verify one small item change before trying a broader workflow.

Can I use the terminal without Claude?

Yes. Commands such as npx lystbot lists and npx lystbot show "Groceries" work directly. A fixed script can also use the documented REST API when it doesn't need language interpretation.

For HTTP workflows, see the shared grocery API examples.