Skip to content

Brick Work MCP server

Brick Work ships an MCP server, so an AI assistant can read your collection and, if you allow it, change it. The server is a thin layer over the REST API: every tool call is one API request with your token, so scopes, Undo, idempotency and the audit log behave exactly as for any other API client.

Before you start

  1. A running Brick Work with the API on (see the README).
  2. An API token. Create one in Tools & Admin → API tokens, or on the server:
brickwork token create --name assistant --scope read

Use --scope read,write only if the assistant may change things. The secret is shown once; keep it in a file only you can read, for example data/mcp-token (mode 600).

Connect an assistant

On the same computer (stdio)

The assistant starts the server itself. With Brick Work installed from source:

brickwork mcp --in-process --token-file data/mcp-token

--in-process uses the local database through the same API routes, with no network. To talk to a running instance instead, give its API address:

brickwork mcp --api-url http://127.0.0.1:3333/api/v2 --token-file data/mcp-token

In an assistant's MCP settings this is one server entry: the command brickwork, the arguments mcp --in-process --token-file /path/to/mcp-token, and the working directory of your Brick Work checkout. With Docker, run the same command through docker compose exec -T brickwork brickwork mcp ....

Over the network (HTTP)

brickwork mcp --transport http --host 127.0.0.1 --port 5000

This serves the MCP endpoint at /mcp next to the app. Each request must carry the caller's own token (Authorization: Bearer ...); the server never falls back to another token. Without a reverse proxy it listens on this computer only; put TLS in front of it before exposing it, and set BW_TRUSTED_PROXIES as described in the README.

Reading and writing

  • Read tools are always available.
  • Write tools appear only when the token has the write scope and the server runs with --allow-write (or BW_MCP_WRITE=1). Both are needed: a write token alone does not enable them.
  • Admin work (settings, source keys, catalogue import, database export, tokens) is never available as a tool. Use the app or the CLI.
  • Every write returns an event_id and, where possible, an undo_url. The undo_event tool takes that id back.
  • A write tool accepts an optional idempotency_key. Pass the same key when retrying a call, and the first result is returned instead of applying the change twice.
  • archive_* tools archive. Nothing is hard-deleted through MCP, and archived records can be restored in the app.
  • Renamed after 0.9.0: the wishlist tools post_wishlists, patch_wishlists_id, delete_wishlists_id, post_wishlists_id_restore and post_wishlists_id_transfer are now create_wishlist, edit_wishlist, archive_wishlist, restore_wishlist and transfer_wishes. A client that calls an old name gets unknown tool (ADR 0017, amendment of 8 Nov 2026).

Items go by number

A tool never asks for a Brick Work item id. Ids are per install, and an assistant has no way to know them. It names an item the way you do, by number:

  • provider: bricklink (the default) or rebrickable. A set has the same number in both.
  • kind: set, part, minifigure, instructions, box, gear, book or catalog.
  • no: the number, such as 1000-1 or 3001.

get_item, get_prices, record_price, refresh_price, import_item and set_figure_missing take these three. Before the call, the server looks the number up (lookup_item does the same on its own). A number that names nothing is not_found. A number that names several items is ambiguous, and the answer lists them as candidates; nothing is written, so ask for a more exact number or the other provider.

A tool that adds something (add_copies, add_stock, add_wish, take_for_gap) takes item as {"provider": "bricklink", "kind": "set", "key": "1000-1"}. provider can be left out. In get_prices the provider also says whose colour number color is, and the colour takes part in the lookup: some BrickLink numbers (legs, for example) name a different item in each colour. record_price takes its color the same way, as the provider's colour number, and stores the Brick Work colour it maps to.

A merged item answers a read with moved and its survivor. The tool reports it as an error, so look the number up again.

Copies, stock lines, wishes, wishlists, storages, lots, events, jobs and orders keep their ids. Take them from the list_* tools, which also filter by number and provider (list_copies with number, for example).

Data and privacy

The assistant sees what its token can read: your sets, parts, prices, storage locations and notes. Brick Work itself sends nothing to the assistant's provider. The assistant client does, so choose a client and provider you are comfortable sharing your collection with, and prefer a read-only token.

Tools and resources

MCP tools and resources lists every read tool, write tool and resource, generated from the server's own tool table when the docs site is built, so it always matches the release.

A resource is a read-only document an assistant can open by its address, for example brickwork://summary or brickwork://items/bricklink/part/3001.