Reference

CLI, MCP and AI agents

Everything here runs through one small program, mb. Install it and sign in once; an AI agent then uses the same mb. An agent reaches it through mb mcp, which serves the same commands as tools, so there is nothing else to install.

Let an AI agent use Miss Blue

Paste this into Claude Code, Codex, Cursor, or any agent that can run commands. It installs mb and the Miss Blue skill, signs in once you approve in your browser, asks you which project to use, and connects itself. It does not send anything until you ask. Your project’s Developers page has the same prompt with the project already filled in.

Set up Miss Blue for me. It sends iMessages from my business numbers through a command line called mb.

1. Run `mb --version`. If mb is missing, install it:
   macOS or Linux: curl -fsSL https://github.com/danest/missblue-cli/releases/latest/download/install.sh | sh
   Windows (PowerShell): irm https://github.com/danest/missblue-cli/releases/latest/download/install.ps1 | iex
2. Install the Miss Blue skill so you know how to use mb: run `mb skill install` (if you are Codex, run `mb skill install --codex`). Read the SKILL.md it installs and follow its rules.
3. Run `mb login`. It opens my browser and waits, for up to 10 minutes, until I approve. Show me the code it prints.
4. Run `mb workspaces` and `mb projects --workspace <id>`, ask me which project to use, then run `mb use <project id>`.
5. If you can add MCP servers, add one named missblue that runs `mb mcp --project <project id>`. In Claude Code: `claude mcp add --scope user missblue -- mb mcp --project <project id>`. In Codex: `codex mcp add missblue -- mb mcp --project <project id>`. If you can't, skip this: the mb commands work either way.
6. Run `mb whoami` and tell me who I am signed in as and which project is selected. Do not send any messages until I ask.

The Miss Blue skill

A skill is a SKILL.md file an agent reads when a task matches it. The Miss Blue skill tells the agent how to use mb: check who it is signed in as first, the commands for common tasks, and the rules it must follow, such as confirming before messaging more than one person and never pasting a key into the chat. Its command list comes from mb itself, so it always matches the version you have.

Add --repo to put it in the current directory instead, to commit it for a team. Running it again after an update refreshes the file, unless you have edited it; then it leaves your copy alone until you add --force. mb skill prints it, and every release publishes it at https://github.com/danest/missblue-cli/releases/latest/download/SKILL.md for an agent that cannot run mb yet.

Setting it up by hand

Install mb and sign in as described below, install the skill, then add Miss Blue to your agent with the one command or file for it. Signed in, the agent gets mb mcp --project <project-id>, which keeps it in that project whatever your default is later. With a project key instead, the key goes in the agent’s environment and there is no project to name.

If an agent reports that it cannot find mb, replace "mb" with the full path that `command -v mb` prints (on Windows, `where.exe mb`).

claude mcp add --transport stdio --scope user missblue -- mb mcp --project <project-id>

claude mcp add --transport stdio --scope user --env MISS_BLUE_API_KEY=mb_live_… missblue -- mb mcp

codex mcp add missblue -- mb mcp --project <project-id>

codex mcp add missblue --env MISS_BLUE_API_KEY=mb_live_… -- mb mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "missblue": {
      "type": "local",
      "command": ["mb", "mcp", "--project", "<project-id>"],
      "enabled": true
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "missblue": {
      "type": "local",
      "command": ["mb", "mcp"],
      "enabled": true,
      "environment": {
        "MISS_BLUE_API_KEY": "mb_live_…"
      }
    }
  }
}

{
  "mcpServers": {
    "missblue": {
      "command": "mb",
      "args": ["mcp", "--project", "<project-id>"]
    }
  }
}

{
  "mcpServers": {
    "missblue": {
      "command": "mb",
      "args": ["mcp"],
      "env": {
        "MISS_BLUE_API_KEY": "mb_live_…"
      }
    }
  }
}

{
  "mcpServers": {
    "missblue": {
      "command": "/full/path/to/mb",
      "args": ["mcp", "--project", "<project-id>"]
    }
  }
}

{
  "mcpServers": {
    "missblue": {
      "command": "/full/path/to/mb",
      "args": ["mcp"],
      "env": {
        "MISS_BLUE_API_KEY": "mb_live_…"
      }
    }
  }
}

{
  "servers": {
    "missblue": {
      "type": "stdio",
      "command": "mb",
      "args": ["mcp", "--project", "<project-id>"]
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "missblue-key",
      "description": "Miss Blue API key",
      "password": true
    }
  ],
  "servers": {
    "missblue": {
      "type": "stdio",
      "command": "mb",
      "args": ["mcp"],
      "env": {
        "MISS_BLUE_API_KEY": "${input:missblue-key}"
      }
    }
  }
}

{
  "mcpServers": {
    "missblue": {
      "command": "mb",
      "args": ["mcp", "--project", "<project-id>"]
    }
  }
}

{
  "mcpServers": {
    "missblue": {
      "command": "mb",
      "args": ["mcp"],
      "env": {
        "MISS_BLUE_API_KEY": "mb_live_…"
      }
    }
  }
}

A failed tool call comes back as a result marked isError, not a transport error, so the agent can read what went wrong and try something else. An agent holding a key reaches that project and nothing more.

Install

The same for every use. One command:

curl -fsSL https://github.com/danest/missblue-cli/releases/latest/download/install.sh | sh

This puts mb in ~/.local/bin (or /usr/local/bin when that is writable), after checking the download against its published SHA-256 checksum. If that folder is not on your PATH yet, the installer prints the line to add. Run it again to update. Then check it:

mb --version

Builds are published for macOS (Apple Silicon and Intel), Linux (x86_64 and arm64) and Windows (x86_64). To install by hand, download the archive for your platform from the latest release and put mb somewhere on your PATH.

Sign in and choose a project

The same for a person and for an agent on your machine.

mb login

mb login prints a short code and opens the console. You approve it there, in a browser you are already signed into, and the token is delivered to the terminal that asked. Nothing goes through a clipboard.

  Your code is  WDJB-MJHT

  Open  https://missblue.dev/device
  and enter it. This code is good for 10 minutes.

When you approve, you choose what it may reach: everything you can, or any combination of organizations and projects. Naming an organization covers the projects inside it, including ones added later. The choice is enforced on every request the sign-in makes: a token granted one project is refused the rest of your account, whatever your role is.

Then mb asks which project to work in. If the sign-in reaches more than one, it lists your organizations, then that organization’s projects, and you pick by number. With exactly one project it is chosen for you. That becomes the default for every command after it.

mb use                  # choose the default project again from the list
mb use <project-id>     # or set it directly
mb whoami               # who you are, and the project you are working in

Any single command can work somewhere else with --project <project-id>, and MISS_BLUE_PROJECT does the same for a whole shell. A project’s id is in its console URL and on its Developers page.

The token is saved to ~/.config/miss-blue/credentials.json with mode 0600. mb logout deletes the local copy. It does not yet revoke the sign-in on the server, so a token that leaked stays valid until it expires; ask us and we will revoke it. If you are handing a machine a credential you may want back in a hurry, scope it narrowly.

On a machine with no browser, such as a server over ssh, pass --no-browser and open the printed URL somewhere else.

Use it from a terminal

After installing and signing in:

mb whoami
mb send --to +15555550100 --text "Your table is confirmed for 7pm"
mb send --to +15555550100 --file receipt.png
mb threads
mb lookup +15555550100
mb problems --only failed

With one number, send uses it. With several it stops and names them rather than guessing, because a reply on the wrong line is worse than a command you have to repeat.

Who has been answering

mb workspaces
mb projects --workspace <workspace-id>
mb activity --project <project-id> --days 7
mb member-activity --project <project-id> --user <user-id>

These need a signed-in person, not a key: how much each person sent is not a question for something with nobody behind it. You see what you could already read: a project you are in, and within it anybody’s work on its numbers. A shared line’s traffic appears on the organization’s own report, counting only your people. The other business on the same number is never shown.

The basics

Add someone, tag them, message them and see what happened. The same commands work signed in or with a project key, and an agent gets them as tools.

mb contact-add --handle +15555550100 --first-name Ada --last-name Lovelace
mb contact --handle +15555550100

mb tag --tag vip --handles +15555550100

mb send --to +15555550100 --text "Hi Ada, your order is ready" --wait delivered

mb message --id <message-id>
mb message --id <message-id> --wait read --timeout 10m

mb threads
mb thread --chat-id <chat-id>

Announcements, scheduled messages and automations

Everything the console’s campaign tools do, mb does too, signed in or with a project key, and an agent gets the same commands as tools. The rules are the console’s: people who opted out are left out, people who have never messaged your number are paced, and a project’s first announcement is read by a person at Miss Blue before it goes out.

mb announce --text "We open at nine from Monday" --list "Spring customers"
mb announce-send --id <announcement-id> --confirm

mb schedule --to +15555550100 --text "See you at ten" --at 2026-10-02T09:00:00-05:00 --time-zone America/Chicago

mb automation-create --name Welcome --tag new-customer --text "Welcome aboard!" --wait 2d --follow-up "Any questions so far?"
mb automation-on --id <automation-id>
mb tag --tag new-customer --handles +15555550100

Lists and tags: mb lists, mb list-create, mb list-add, mb tags, mb tag. What is queued or running: mb announcements, mb scheduled, mb automation-runs, and for one person, mb automation-status --handle: which automations they are in, how the last ones ended, and which would start for them. The skill tells an agent to show you the preview and get your yes before any announcement, never to automate messages to people who have not opted in, and to schedule for the recipient’s local time.

Change one thing about an automation without restating the rest: mb automation-update --id <id> --stop-on-reply false keeps it going after a reply, and --from auto or --from <number-id> moves it between Auto and one number. If a number it was pinned to leaves your project, it moves to another of your numbers, or is switched off when there is none, and mb automation shows a note saying which.

Business hours

mb automation-create --name Welcome --tag new-customer --text "Welcome aboard!" \
  --hours 08:00-18:00 --days mon-fri
mb automation-update --id <id> --time-zone America/Chicago
mb automation-update --id <id> --any-time

--hours keeps an automation to business hours: Eastern time unless you pass --time-zone, every day unless you pass --days (mon-fri, mon,wed,fri, weekends). A tag added at 11 PM still starts the automation then; its message waits for 8 AM. An update changes only the part you name, and --any-time clears the hours.

How an automation is doing

mb automation-stats --id <id>             # the last 30 days, step by step
mb automation-stats --id <id> --all
mb automation-replies --id <id> --step 4  # who answered step 4, and what they said

automation-stats gives each step’s sent, delivered, read (opened), replied and opted out, with reply and opt-out rates, and how people’s runs ended. Read only counts people with read receipts on, so it is at least that many. automation-replies lists every reply, newest first, with the message it answered and a link to the conversation.

A/B/C tests

mb automation-create --name Tour --tag toured --text "Thanks for coming by!" \
  --text-b "Want a second look?" --weights 50,50 --wait 1d \
  --follow-up "Still thinking it over?" --follow-up-b "Happy to set up another visit."
mb automation-stats --id <id>                                  # each version, and a verdict
mb variant-use --automation <id> --step 1 --letter B           # everybody new gets B
mb variant-weights --automation <id> --step 1 --weights 70,30
mb announce --text "Open house Saturday." --text-b "Come see it Saturday?" \
  --list Leads --test-first 20% --pick-after 4h

--text is version A; --text-b and --text-c add versions, split by --weights or evenly. Each person keeps their version for the follow-up. automation-stats puts the versions side by side and says whether one is ahead, or how many more people it needs first. variant-use sends one version to everybody who reaches that step from now on. variant-weights changes the split on the first step with versions, for people given a version from now on; later steps follow it. An announcement with --test-first tries the versions on that share of the list, then sends the rest the one with the best reply rate.

Run it on a server or in CI

Nobody can approve a sign-in there, so use a project key instead of mb login. A key comes from a project’s Developers page, under API keys, and belongs to that one project. Install mb as above, then:

export MISS_BLUE_API_KEY=mb_live_…
mb whoami
mb send --to +15555550100 --text "Your order has shipped"

MISS_BLUE_API_KEY wins over a saved sign-in. Keep it in your CI or server secrets, never in a file you commit.

Every command

The same list in both places. A CLI command and an MCP tool of the same name do the same thing and take the same arguments: --allow-duplicate on the command line is allow_duplicate to an agent.

* required. Signing in and choosing a project (login, logout, use) are above.