MCP tools
All MCP tools are served by the Pillbox MCP server and consumed by AI agents (Claude, Cursor, etc.). Responses are plain structured text — not JSON — so the LLM can read them directly without parsing.
Errors follow a uniform format: error: <code>, message: <description>, plus additional fields when relevant.
Pills and prescriptions belong to a bottle (project-local database). Capsules are stored in the global database (~/.pillbox/pillbox.db).
Pill tools
Section titled “Pill tools”Pills are structured memory entries attached to a prescription (work session) inside a bottle.
pill_store
Section titled “pill_store”Creates a new pill.
| Parameter | Type | Required | Description |
|---|---|---|---|
prescription_id | string (UUID v7) | yes | Open prescription to attach this pill to |
title | string (1–255) | yes | Short descriptive title |
content | string (1–5000) | yes | Full content of the pill |
compound | string | yes | Category — free-text string |
author_name | string | yes | Author name — see author identity |
author_email | string | yes | Author email — see author identity |
Returns the id of the new pill.
pill_read
Section titled “pill_read”Retrieves a pill by UUID.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Pill UUID |
Returns id, prescription, created, compound, title, and full content. Returns a not_found error if the pill does not exist.
pill_revise
Section titled “pill_revise”Updates a pill’s title, content, or compound.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Pill UUID |
title | string (1–255) | no | New title |
content | string (1–5000) | no | New content |
compound | string | no | New compound |
Returns id, compound, and updated title.
pill_discard
Section titled “pill_discard”Soft-deletes a pill (the record is marked deleted, not removed).
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Pill UUID |
Returns id and deleted_at timestamp.
pill_search
Section titled “pill_search”Full-text search over pills using FTS5 prefix matching and Jaro-Winkler fuzzy scoring.
At least one of query or compound must be provided. If only compound is passed, lists pills of that compound without FTS filtering. If the strict pass returns zero results, the server automatically retries with fuzzy (Jaro-Winkler) expansion — the response includes used_fuzzy: true when that happened.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | no | FTS search query — terms split on whitespace and -_/.:, joined with OR |
bottle_id | string (UUID v7) | no | Restrict to a specific bottle |
compound | string | no | Filter by compound type |
limit | integer | no | Max results (default: 20) |
fuzzy | boolean | no | Force fuzzy (Jaro-Winkler) match from the start, skipping the strict pass. Default: false |
Returns matched pills with id, compound, title, and a content snippet. Returns No pills found. when the query matches nothing.
pill_compounds
Section titled “pill_compounds”Lists distinct pill compounds with their frequency, ordered by count descending. Useful to discover available categories before searching.
| Parameter | Type | Required | Description |
|---|---|---|---|
bottle_id | string (UUID v7) | no | Restrict to a specific bottle |
limit | integer | no | Max compounds to return |
Returns a list of compound names with their pill count.
Capsule tools
Section titled “Capsule tools”Capsules are global memory entries — conventions, workflows, and environment context shared across all projects.
capsule_store
Section titled “capsule_store”Creates a new capsule in the global database.
| Parameter | Type | Required | Description |
|---|---|---|---|
title | string (1–255) | yes | Short descriptive title |
content | string (1–5000) | yes | Full content of the capsule |
compound | string | yes | Category — free-text string |
Returns the id of the new capsule.
capsule_read
Section titled “capsule_read”Retrieves a capsule by UUID.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Capsule UUID |
Returns id, created, compound, title, and full content. Returns a not_found error if the capsule does not exist.
capsule_revise
Section titled “capsule_revise”Updates a capsule’s title, content, or compound.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Capsule UUID |
title | string (1–255) | no | New title |
content | string (1–5000) | no | New content |
compound | string | no | New compound |
Returns id, compound, and updated title.
capsule_discard
Section titled “capsule_discard”Soft-deletes a capsule.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Capsule UUID |
Returns id and deleted_at timestamp.
capsule_search
Section titled “capsule_search”Full-text search over capsules using FTS5 prefix matching and Jaro-Winkler fuzzy scoring. Capsules are global — not filtered by project.
At least one of query or compound must be provided. If only compound is passed, lists capsules of that compound without FTS filtering. If the strict pass returns zero results, the server automatically retries with fuzzy (Jaro-Winkler) expansion — the response includes used_fuzzy: true when that happened.
| Parameter | Type | Required | Description |
|---|---|---|---|
query | string | no | FTS search query — terms split on whitespace and -_/.:, joined with OR |
compound | string | no | Filter by compound type |
limit | integer | no | Max results (default: 20) |
fuzzy | boolean | no | Force fuzzy (Jaro-Winkler) match from the start, skipping the strict pass. Default: false |
Returns matched capsules with id, compound, title, and a content snippet. Returns No capsules found. when the query matches nothing.
capsule_compounds
Section titled “capsule_compounds”Lists distinct capsule compounds with their frequency, ordered by count descending. Scope is global (all capsules across projects).
| Parameter | Type | Required | Description |
|---|---|---|---|
limit | integer | no | Max compounds to return |
Returns a list of compound names with their capsule count.
Prescription tools
Section titled “Prescription tools”A prescription is an open work session inside a bottle. Pills must be attached to a prescription. Multiple prescriptions can be open per bottle at the same time.
prescription_open
Section titled “prescription_open”Opens a new prescription for a bottle. To reopen a previously closed prescription, use prescription_reopen instead.
| Parameter | Type | Required | Description |
|---|---|---|---|
bottle_id | string (UUID v7) | yes | Bottle to open the prescription in |
title | string (1–255) | yes | Descriptive title for the session |
author_name | string | yes | Author name — see author identity |
author_email | string | yes | Author email — see author identity |
Returns id, title, and started_at. Always opens a new prescription; to reuse an existing open prescription, list open ones with bottle_context and pass its id directly.
prescription_close
Section titled “prescription_close”Closes an open prescription (sets ended_at).
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Prescription ID |
Returns id, title, started_at, and ended_at.
prescription_reopen
Section titled “prescription_reopen”Reopens a closed prescription to allow editing or adding pills. Idempotent: if the prescription is already open, returns it unchanged.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Prescription UUID |
Returns the prescription with its current state.
prescription_read
Section titled “prescription_read”Retrieves a prescription by ID.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Prescription ID |
Returns id, title, started_at, and ended_at. Returns a not_found error if the prescription does not exist.
prescription_context
Section titled “prescription_context”Pills of a specific prescription with id, compound, title, and a 300-char snippet. Newlines in pill content are rendered as \n to keep each pill on a single visual line. Use after bottle_context to drill into a specific work session. For the full content of an individual pill, use pill_read.
| Parameter | Type | Required | Description |
|---|---|---|---|
prescription_id | string (UUID v7) | yes | Prescription to inspect |
limit | integer | no | Max pills to return (default: 30) |
Returns an empty response if the prescription does not exist.
prescription_discard
Section titled “prescription_discard”Soft-deletes a prescription and all its pills in cascade.
| Parameter | Type | Required | Description |
|---|---|---|---|
id | string (UUID v7) | yes | Prescription ID |
Returns a confirmation message.
Bottle tools
Section titled “Bottle tools”A bottle represents a project — it holds a local SQLite database with all prescriptions and pills for that project.
bottle_create
Section titled “bottle_create”Registers a new bottle. The directory is derived server-side from the cwd of the pillbox process (for scope='local') or from the user home (for scope='global') — agents must not pass a directory parameter.
| Parameter | Type | Required | Description |
|---|---|---|---|
name | string (1–255) | yes | Slug (usually the folder name, kebab-case) |
display_name | string (1–255) | yes | Human-readable name |
scope | local | global | no | Whether to use a local or global database (default: local) |
Returns id, name, display_name, directory, and scope.
bottle_context
Section titled “bottle_context”Navigable index of a bottle’s prescriptions: id, title, status, dates, and pill count. Use at session start to discover what work sessions exist. To drill into a specific prescription’s pills, use prescription_context with its id.
| Parameter | Type | Required | Description |
|---|---|---|---|
bottle_id | string (UUID v7) | yes | Bottle to index |
limit | integer | no | Max prescriptions to return (default: 30) |
bottle_list
Section titled “bottle_list”Lists all registered bottles. No parameters.
Returns one entry per bottle with name, scope, id, and database path. ● means the bottle’s database is accessible; ○ with [unlinked] means the database file no longer exists on disk.
bottle_vinculate
Section titled “bottle_vinculate”Registers an existing local bottle database into the calling user’s global registry. Use this when a second OS user needs to access a bottle created by another user on the same machine.
| Parameter | Type | Required | Description |
|---|---|---|---|
directory | string | no | Absolute path to the directory containing .pillbox/pillbox.db. Defaults to the process cwd. |
Returns status: "linked" on success or status: "already_linked" if the bottle was already registered. Both are exit-0 conditions. Error codes specific to this tool: db_not_found, circular_link, no_bottle_in_db.
Error codes
Section titled “Error codes”| Code | Meaning |
|---|---|
not_found | The requested resource does not exist |
prescription_required | The provided prescription_id does not exist or is already closed |
validation_error | One or more input fields failed validation |
invalid_input | The input could not be parsed |
internal_error | Unexpected server error |
db_not_found | No .pillbox/pillbox.db found at the target directory (bottle_vinculate) |
circular_link | The target directory is the global database directory itself (bottle_vinculate) |
no_bottle_in_db | The database file exists but contains no registered bottle (bottle_vinculate) |