bring-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,22 @@
1
+ # Copy to .env (chmod 600) and fill in. Never commit .env.
2
+
3
+ # Bring! account
4
+ BRING_EMAIL=
5
+ BRING_PASSWORD=
6
+ # List used when a tool is called without a list name (default: the first list)
7
+ # BRING_DEFAULT_LIST=Shopping
8
+
9
+ # --- Remote server only (claude.ai connector) ---
10
+
11
+ # Password asked on the OAuth page when adding the connector (20+ characters)
12
+ # Generate one with: openssl rand -base64 30
13
+ MCP_PASSWORD=
14
+
15
+ # Public base URL of the server (your reverse proxy vhost), without trailing slash
16
+ PUBLIC_URL=https://bring.example.com
17
+
18
+ # Optional
19
+ # PORT=8765
20
+ # LISTEN_HOST=127.0.0.1
21
+ # OAuth redirect URIs a client may register (comma-separated). Default: claude.ai's callback.
22
+ # ALLOWED_REDIRECT_URIS=https://claude.ai/api/mcp/auth_callback,https://claude.com/api/mcp/auth_callback
@@ -0,0 +1 @@
1
+ * text=auto eol=lf
@@ -0,0 +1,14 @@
1
+ version: 2
2
+ updates:
3
+ - package-ecosystem: pip
4
+ directory: /
5
+ schedule:
6
+ interval: weekly
7
+ - package-ecosystem: docker
8
+ directory: /
9
+ schedule:
10
+ interval: weekly
11
+ - package-ecosystem: github-actions
12
+ directory: /
13
+ schedule:
14
+ interval: weekly
@@ -0,0 +1,29 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ pull_request:
6
+
7
+ permissions:
8
+ contents: read
9
+
10
+ jobs:
11
+ test:
12
+ runs-on: ubuntu-latest
13
+ strategy:
14
+ matrix:
15
+ python: ["3.12", "3.13"]
16
+ steps:
17
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
18
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
19
+ with:
20
+ python-version: ${{ matrix.python }}
21
+ - run: pip install -e ".[dev]"
22
+ - run: ruff check .
23
+ - run: pytest -q
24
+
25
+ docker:
26
+ runs-on: ubuntu-latest
27
+ steps:
28
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
29
+ - run: docker build -t bring-mcp .
@@ -0,0 +1,64 @@
1
+ # Push a tag vX.Y.Z (matching the version in pyproject.toml) to publish the
2
+ # package on PyPI, then the server on the MCP Registry (registry.modelcontextprotocol.io).
3
+ # PyPI uses trusted publishing (no token): add this workflow as a trusted
4
+ # publisher on pypi.org, environment "pypi". The registry uses GitHub OIDC.
5
+ name: Release
6
+
7
+ on:
8
+ push:
9
+ tags: ["v*"]
10
+
11
+ permissions:
12
+ contents: read
13
+
14
+ jobs:
15
+ pypi:
16
+ runs-on: ubuntu-latest
17
+ environment: pypi
18
+ permissions:
19
+ id-token: write
20
+ steps:
21
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
22
+ - uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
23
+ with:
24
+ python-version: "3.13"
25
+ - name: Check the tag matches the package version
26
+ run: |
27
+ version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
28
+ test "v$version" = "$GITHUB_REF_NAME" || { echo "tag $GITHUB_REF_NAME != pyproject version $version"; exit 1; }
29
+ - run: pip install -e ".[dev]" build
30
+ - run: ruff check .
31
+ - run: pytest -q
32
+ - run: python -m build
33
+ - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
34
+
35
+ mcp-registry:
36
+ needs: pypi
37
+ runs-on: ubuntu-latest
38
+ permissions:
39
+ id-token: write
40
+ env:
41
+ MCP_PUBLISHER_VERSION: v1.8.9
42
+ steps:
43
+ - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
44
+ - uses: sigstore/cosign-installer@756fe2d284c7292c4e9b62c8a28f1e5629c59532 # v4.1.3
45
+ - name: Download and verify mcp-publisher
46
+ run: |
47
+ set -euo pipefail
48
+ archive="mcp-publisher_linux_amd64.tar.gz"
49
+ base_url="https://github.com/modelcontextprotocol/registry/releases/download/${MCP_PUBLISHER_VERSION}"
50
+ curl --fail --location --silent --show-error --output "$archive" "$base_url/$archive"
51
+ curl --fail --location --silent --show-error --output "$archive.sigstore.json" "$base_url/$archive.sigstore.json"
52
+ cosign verify-blob \
53
+ --bundle "$archive.sigstore.json" \
54
+ --certificate-identity "https://github.com/modelcontextprotocol/registry/.github/workflows/release.yml@refs/tags/${MCP_PUBLISHER_VERSION}" \
55
+ --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
56
+ "$archive"
57
+ tar xzf "$archive" mcp-publisher
58
+ - name: Set the version in server.json
59
+ run: |
60
+ version="${GITHUB_REF_NAME#v}"
61
+ jq --arg v "$version" '.version = $v | .packages[].version = $v' server.json > server.tmp
62
+ mv server.tmp server.json
63
+ - run: ./mcp-publisher login github-oidc
64
+ - run: ./mcp-publisher publish
@@ -0,0 +1,21 @@
1
+ # Secrets and runtime data: never commit
2
+ .env
3
+ data/
4
+ *.sqlite
5
+ *.sqlite-journal
6
+
7
+ # Python
8
+ .venv/
9
+ __pycache__/
10
+ *.py[cod]
11
+ *.egg-info/
12
+ build/
13
+ dist/
14
+ .pytest_cache/
15
+ .ruff_cache/
16
+
17
+ # Editors / OS
18
+ .vscode/
19
+ .idea/
20
+ .DS_Store
21
+ Thumbs.db
@@ -0,0 +1,144 @@
1
+ # AGENTS.md
2
+
3
+ Notes for coding agents (and humans) working on this repository. The README covers
4
+ what the project does and how to set it up; this file covers what to keep in mind
5
+ when changing it.
6
+
7
+ ## Layout
8
+
9
+ - `src/bring_mcp/tools.py`: every tool and prompt, plus `INSTRUCTIONS`. `register()`
10
+ adds them to any `MCPServer`; it is the only place tools are defined.
11
+ - `src/bring_mcp/bring_client.py`: wrapper around bring-api (login, lists by name,
12
+ catalog names, recipe parser) and the name-matching helpers (`normalize`,
13
+ `find`, `merge_spec`).
14
+ - `src/bring_mcp/__main__.py`: local stdio server (`bring-mcp`).
15
+ `src/bring_mcp/server.py`: remote HTTP server for claude.ai (OAuth, audit log).
16
+ - `src/bring_mcp/auth.py`: OAuth provider (password page, lockout, redirect
17
+ allowlist). Ported from proton-mcp's `remote/auth.py`: a security fix in one
18
+ probably applies to the other.
19
+ - `src/bring_mcp/store.py`: SQLite key-value store (OAuth clients/tokens, staples).
20
+ `src/bring_mcp/staples.py`: staples, and the cron command `python -m bring_mcp.staples`.
21
+ - `deploy/`: example reverse-proxy configs. `docs/deploy.md`: the full server guide.
22
+
23
+ ## Commands
24
+
25
+ ```bash
26
+ pip install -e ".[dev]"
27
+ pytest
28
+ ruff check .
29
+ docker build -t bring-mcp .
30
+ ```
31
+
32
+ Tests need no Bring account and no network: `tests/test_tools.py` runs the tools
33
+ against a `FakeClient`, `tests/test_client.py` fakes `bring_api.Bring` including
34
+ its private attributes. `server.py` reads its configuration at import time, so
35
+ `tests/test_server.py` imports it in a subprocess.
36
+
37
+ ## Releasing
38
+
39
+ Bump `version` in `pyproject.toml`, commit, then push a tag `vX.Y.Z` with the same
40
+ version. `.github/workflows/release.yml` checks the tag matches, runs the tests,
41
+ publishes to PyPI (trusted publishing, environment `pypi`), then publishes
42
+ `server.json` to the MCP Registry as `io.github.vdeabreu/bring-mcp` (GitHub OIDC). The
43
+ registry checks ownership through the `mcp-name:` comment at the top of the
44
+ README: keep it.
45
+
46
+ ## Invariants: don't break these
47
+
48
+ - **Bounded, single-line inputs.** Item names, specs and list names go through the
49
+ `ItemName` / `Spec` / `ListArg` types in `tools.py` (no control characters,
50
+ length limits), and a call takes at most `MAX_ITEMS` items. Use them for any new
51
+ argument.
52
+ - **No account-level tools.** The server reads and edits list items and staples
53
+ only. Don't add tools that delete lists, share them, invite users or change
54
+ account settings.
55
+ - **Annotations stay honest.** Read tools are `readOnlyHint`; `remove_items` and
56
+ `set_staples_list` are `destructiveHint`, so clients can ask before running them.
57
+ - **Recipe pages are untrusted.** `fetch_recipe` passes the URL to Bring's parser
58
+ (the server never downloads the page itself), accepts `http(s)` only and returns
59
+ only ingredient names and specs. `INSTRUCTIONS` tell the model not to follow text
60
+ from recipe pages; keep it that way.
61
+ - **Errors are readable, internals aren't.** Bring and lookup errors
62
+ (`BringException`, `ValueError`) become a `ToolError` with a short message the
63
+ model can act on (e.g. the list of available lists). Any other exception is logged
64
+ with its traceback and reported as a generic message.
65
+ - **Shared lists are untrusted too.** Item names come from everyone the list is
66
+ shared with; `INSTRUCTIONS` tell the model to treat them as data.
67
+ - **Private data directory.** `Store` creates the directory 0700 and the SQLite
68
+ file 0600: it holds OAuth tokens.
69
+ - **Remote hardening.** The HTTP server refuses a non-loopback `LISTEN_HOST` unless
70
+ `ALLOW_NON_LOOPBACK_LISTEN=true` (`_check_listen_host`); `MCP_PASSWORD` must be
71
+ 20+ characters; OAuth registration only accepts the claude.ai callback URLs; the
72
+ login page sends anti-framing headers. Every tool call is logged with its
73
+ arguments (shopping items aren't sensitive enough to hide).
74
+
75
+ ## Bring and bring-api behaviour (learned the hard way)
76
+
77
+ - **bring-api hides what we need.** The catalog translations, the list locale and
78
+ the translate function are name-mangled private attributes
79
+ (`_Bring__translations`, `_Bring__locale`, `_Bring__translate`). That's why
80
+ bring-api is pinned in `pyproject.toml`: before bumping it, check these still
81
+ exist and run the tests.
82
+ - **Catalog keys are Swiss German.** Bring identifies catalog items by their de-CH
83
+ name (`BRING_DEFAULT_LOCALE`), so there is no translation table for de-CH: for a
84
+ de-CH list, the catalog is the table's keys. The recipe parser returns these keys
85
+ too, hence `_to_list_language()`.
86
+ - **Names are in the list's language both ways.** `get_list` returns items
87
+ translated to the list's language, and `batch_update_list` translates `itemId`
88
+ back to the catalog key. So always send names in the list's language, spelled
89
+ as in the catalog (`catalog_name()`): a name that doesn't match exactly is stored
90
+ as a custom item, without icon or section.
91
+ - **Matching is ours.** Bring doesn't deduplicate "tomate" and "Tomates".
92
+ `normalize()` ignores case, accents, œ/æ and a final s/x on words longer than 3
93
+ letters; `find()` uses it to merge with existing items.
94
+ - **One operation, three effects.** `ADD` with an existing item's `uuid` replaces
95
+ its spec (that's how `update_item` and merging work). `COMPLETE` moves an item to
96
+ "recently bought"; `REMOVE` works on both sections.
97
+ - **Sessions.** Login is lazy (first tool call), so the server starts without
98
+ network. bring-api refreshes the access token by itself; when the refresh token
99
+ expires it raises `BringAuthException`, and `BringClient._call()` logs in again
100
+ once. A failed login itself is never retried (wrong credentials would double the
101
+ attempts on every call and risk a rate limit on the Bring account). List settings (locales) are loaded at login: a list created later uses the
102
+ account locale until the next login.
103
+ - **Accounts** must sign in with email and password; Google/Apple sign-in accounts
104
+ need a password set in the Bring app first.
105
+ - **de-CH only accounts.** bring-api loads no translation table for de-CH, so the
106
+ catalog comes from the `articles.de-CH.json` file bring-api ships.
107
+
108
+ ## MCP SDK notes (mcp 2.3.0)
109
+
110
+ - The server class is `mcp.server.mcpserver.MCPServer`. `Tool` fields are
111
+ snake_case (`input_schema`, `annotations.read_only_hint`).
112
+ - `Annotated[..., Field(...)]` parameters become JSON Schema constraints and are
113
+ validated before the tool runs (a bad argument is a `ToolError`).
114
+ - A tool returning `dict` has no output schema: `call_tool()` gives
115
+ `structured_content=None` and the JSON in `content[0].text` (see the `call`
116
+ helper in `tests/test_tools.py`).
117
+
118
+ ## Deployment notes
119
+
120
+ - Unlike proton-mcp, the container uses a normal Docker network, not the host
121
+ network: it only talks to the internet, and the host network would let it reach
122
+ other loopback services (such as Proton Mail Bridge on the same host). So in
123
+ `compose.yml` it listens on 0.0.0.0 inside the container, the port is published
124
+ on `127.0.0.1` only, and `FORWARDED_ALLOW_IPS` trusts Docker's default pool
125
+ (172.16.0.0/12) because requests come from the Docker gateway. Never `"*"`: uvicorn
126
+ then takes the *leftmost* `X-Forwarded-For` value, which the client controls, so
127
+ anyone could forge the address in "wrong password from ..." log lines.
128
+ - The reverse proxy should target `127.0.0.1:8765`, not `localhost` (Docker
129
+ doesn't publish the port on `::1`).
130
+ - Rebuilding the container keeps OAuth tokens (`data/bring-mcp.sqlite`), so
131
+ claude.ai stays connected. Raising the password rules (e.g. the 20-character
132
+ minimum) stops the server from starting until `.env` is updated.
133
+
134
+ ## Conventions
135
+
136
+ - Python 3.12+, ruff with line length 120. Code, docs and tool descriptions in
137
+ English; the model answers in the user's language anyway.
138
+ - Tool docstrings are what the model reads: keep them accurate and short.
139
+ - Add a test with each change, especially for name matching, input validation and
140
+ anything that reads bring-api's private attributes.
141
+ - Dependencies and the Docker base image are pinned (image by digest, actions by
142
+ SHA). Dependabot opens the update PRs.
143
+ - Keep the repo generic: no personal domains, IPs or host names (use
144
+ `bring.example.com`).
@@ -0,0 +1 @@
1
+ @AGENTS.md
@@ -0,0 +1,12 @@
1
+ # Base image pinned by digest (the tag is on the FROM line); Dependabot proposes updates.
2
+ FROM python:3.15-slim@sha256:65a65fc7b30b06cb6df4930fd4650697cb23f4c2698ab81fc87e4b031bc36928
3
+ WORKDIR /app
4
+ COPY pyproject.toml README.md ./
5
+ COPY src ./src
6
+ RUN pip install --no-cache-dir "uvicorn==0.54.0" . \
7
+ && useradd -u 1000 -m app && mkdir /data && chown app /data
8
+ USER app
9
+ ENV DATA_DIR=/data PYTHONUNBUFFERED=1 PYTHONDONTWRITEBYTECODE=1
10
+ EXPOSE 8765
11
+ HEALTHCHECK --interval=60s --timeout=5s CMD python -c "import os, urllib.request; urllib.request.urlopen(f'http://127.0.0.1:{os.environ.get(\"PORT\", \"8765\")}/health')"
12
+ CMD ["python", "-m", "bring_mcp.server"]
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Victor De Abreu
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,195 @@
1
+ Metadata-Version: 2.5
2
+ Name: bring-mcp
3
+ Version: 0.1.0
4
+ Summary: MCP server for Bring! shopping lists (local stdio or remote claude.ai connector)
5
+ Project-URL: Homepage, https://github.com/vdeabreu/bring-mcp
6
+ Project-URL: Issues, https://github.com/vdeabreu/bring-mcp/issues
7
+ Author: Victor De Abreu
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: bring,claude,groceries,mcp,mcp-server,recipes,shopping-list
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Intended Audience :: End Users/Desktop
13
+ Classifier: Operating System :: OS Independent
14
+ Classifier: Programming Language :: Python :: 3
15
+ Classifier: Topic :: Home Automation
16
+ Requires-Python: >=3.12
17
+ Requires-Dist: bring-api==1.1.2
18
+ Requires-Dist: mcp==2.3.0
19
+ Requires-Dist: uvicorn>=0.30
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=8; extra == 'dev'
22
+ Requires-Dist: ruff>=0.6; extra == 'dev'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # bring-mcp
26
+
27
+ [![PyPI](https://img.shields.io/pypi/v/bring-mcp)](https://pypi.org/project/bring-mcp/)
28
+ [![CI](https://github.com/vdeabreu/bring-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vdeabreu/bring-mcp/actions/workflows/ci.yml)
29
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/vdeabreu/bring-mcp/blob/main/LICENSE)
30
+
31
+ <!-- mcp-name: io.github.vdeabreu/bring-mcp -->
32
+
33
+ An [MCP](https://modelcontextprotocol.io) server that gives Claude (or any MCP
34
+ client) access to your **[Bring!](https://www.getbring.com)** shopping lists.
35
+
36
+ - **Lists**: read, add (with quantities), update, check off and remove items.
37
+ Names are matched against the Bring catalog, so items get their section and icon.
38
+ - **Recipes**: extract the ingredients of a recipe page with Bring's own parser,
39
+ then add them in one go.
40
+ - **Staples**: keep a list of items you buy every week and add the missing ones,
41
+ from Claude or from cron (no LLM involved).
42
+ - Runs **locally** for Claude Desktop (stdio), or **remotely** as a claude.ai
43
+ custom connector (streamable HTTP + OAuth).
44
+
45
+ > Unofficial project, not affiliated with or endorsed by Bring! Labs AG. It uses
46
+ > [bring-api](https://github.com/miaucl/bring-api), an unofficial client of the
47
+ > Bring! API, which may change without notice.
48
+
49
+ ## Why this one
50
+
51
+ Other Bring! MCP servers map the API call by call (load list, save item, remove
52
+ item...). This one gives the model tools shaped like the tasks you ask for:
53
+
54
+ - **"Add what I need for this recipe"**: Bring's own recipe parser extracts the
55
+ ingredients of a page in your list's language, and flags pantry items (salt,
56
+ oil) so the model can ask before adding them.
57
+ - **"Add 2 more litres of milk"**: an item already on the list gets its quantity
58
+ merged instead of replaced, and names are matched against the Bring catalog
59
+ (case, accents, simple plurals), so items land in the right section with their icon.
60
+ - **Weekly staples**: keep the list of things you always buy and add the missing
61
+ ones in one call, or from cron without any LLM.
62
+ - **Works in claude.ai on the web and on your phone**, not only in Claude Desktop:
63
+ a remote mode with OAuth, Docker and reverse-proxy configs, and a full
64
+ [deployment guide](https://github.com/vdeabreu/bring-mcp/blob/main/docs/deploy.md).
65
+
66
+ ## Tools
67
+
68
+ | Tool | What it does |
69
+ | --- | --- |
70
+ | `list_lists` | Names of your Bring lists. |
71
+ | `get_list` | Items to buy and recently bought items. |
72
+ | `add_items` | Add items with an optional spec (`"6"`, `"500 g"`, `"organic"`). An item already on the list gets its spec merged (`1 L + 2 L`). |
73
+ | `update_item` | Replace the spec of an item. |
74
+ | `complete_items` | Check items off (they move to "recently bought"). |
75
+ | `remove_items` | Remove items. |
76
+ | `fetch_recipe` | Ingredients of a recipe URL, in the list's language, with a `pantry` flag (salt, oil...). Adds nothing by itself. |
77
+ | `get_staples_list` / `set_staples_list` | Read or replace your staples. |
78
+ | `add_staples` | Add the staples that aren't on the list yet. |
79
+
80
+ Every tool takes an optional `list` (name, case-insensitive); without it, the
81
+ server uses `BRING_DEFAULT_LIST`, or your first list.
82
+
83
+ Prompts: `add_recipe`, `clean_up_list`, `weekly_shopping`.
84
+
85
+ ## Local setup (Claude Desktop)
86
+
87
+ Requirements: [uv](https://docs.astral.sh/uv/) (or Python 3.12+) and a Bring!
88
+ account that signs in with an email and password (if you use Google or Apple
89
+ sign-in, set a password in the Bring app).
90
+
91
+ Add the server to `claude_desktop_config.json`. Open it from Claude Desktop →
92
+ Settings → Developer → Edit Config, or directly:
93
+
94
+ - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
95
+ - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
96
+ - Linux: `~/.config/Claude/claude_desktop_config.json`
97
+
98
+ ```json
99
+ {
100
+ "mcpServers": {
101
+ "bring": {
102
+ "command": "uvx",
103
+ "args": ["bring-mcp"],
104
+ "env": {
105
+ "BRING_EMAIL": "you@example.com",
106
+ "BRING_PASSWORD": "your-bring-password",
107
+ "BRING_DEFAULT_LIST": "Shopping"
108
+ }
109
+ }
110
+ }
111
+ }
112
+ ```
113
+
114
+ Fully quit and restart Claude Desktop after editing the file.
115
+
116
+ Without uv: `pip install bring-mcp`, then use `"command": "bring-mcp"` (the full
117
+ path to that script if it isn't on your `PATH`) and no `args`.
118
+
119
+ ### Configuration
120
+
121
+ | Variable | Default | |
122
+ | --- | --- | --- |
123
+ | `BRING_EMAIL` | (required) | Bring account email |
124
+ | `BRING_PASSWORD` | (required) | Bring account password |
125
+ | `BRING_DEFAULT_LIST` | *(first list)* | List used when a tool gets no `list` |
126
+ | `DATA_DIR` | `~/.bring-mcp` | Where the SQLite file (staples, and OAuth tokens in remote mode) is kept |
127
+
128
+ The config file holds your Bring password: keep it readable by you only.
129
+
130
+ ## Remote setup (claude.ai connector)
131
+
132
+ `python -m bring_mcp.server` (or `bring-mcp-remote`) serves the same tools over
133
+ streamable HTTP, behind a single-user OAuth password page, for claude.ai on the
134
+ web and mobile. A Dockerfile and compose file are included, plus Apache and Caddy
135
+ configs that only let Anthropic's IP ranges reach `/mcp`.
136
+
137
+ See **[docs/deploy.md](https://github.com/vdeabreu/bring-mcp/blob/main/docs/deploy.md)** for the full guide (Docker, reverse
138
+ proxy, claude.ai, weekly staples).
139
+
140
+ ## Security
141
+
142
+ - **What's at stake.** Your Bring password gives full access to your Bring
143
+ account; this server can read and change your lists. It has no tool to
144
+ delete lists, change account settings or invite people.
145
+ - **Recipe pages are untrusted.** `fetch_recipe` asks Bring's servers to parse the
146
+ page (this server never downloads it) and returns only ingredient names and
147
+ quantities. The server instructions still tell the model not to follow text
148
+ found there. Only `http(s)` URLs are accepted.
149
+ - **Inputs are bounded.** Item names and specs are single-line and length-limited,
150
+ and a call handles at most 100 items. `remove_items` and `set_staples_list` carry
151
+ the MCP `destructiveHint`, so clients can ask before running them.
152
+ - **Remote mode**:
153
+ - OAuth with a 20+ character password, a lockout after 5 failures, and tokens
154
+ stored in SQLite.
155
+ - Only claude.ai's callback can be registered as redirect URI, and the number of
156
+ clients is capped.
157
+ - The password page says which client asks and can't be framed by another site.
158
+ - `/mcp` is restricted to Anthropic's outbound IPs by the reverse proxy.
159
+ - The server refuses to listen on a public address, every tool call is logged,
160
+ and the container is read-only and unprivileged.
161
+ - **Remote mode, known limits:**
162
+ - The lockout is global: anyone can make *new* logins wait 15 minutes by failing
163
+ 5 times. Tokens already issued keep working.
164
+ - Anyone can add your server URL as a connector in *their own* claude.ai account
165
+ and send you the resulting authorization link. If you type your password, their
166
+ account gets access. Only type it right after clicking *Connect* yourself.
167
+
168
+ Keep `.env` and `claude_desktop_config.json` private. To report a vulnerability,
169
+ see [SECURITY.md](https://github.com/vdeabreu/bring-mcp/blob/main/SECURITY.md).
170
+
171
+ ## Limitations
172
+
173
+ - Catalog matching relies on bring-api's translation tables, read through private
174
+ attributes; bring-api is pinned for that reason.
175
+ - Name matching ignores case, accents and a final `s`/`x`; it doesn't know other
176
+ plurals or synonyms.
177
+ - Item photos, list sharing, notifications and loyalty cards are not supported.
178
+
179
+ ## Development
180
+
181
+ ```bash
182
+ git clone https://github.com/vdeabreu/bring-mcp && cd bring-mcp
183
+ pip install -e ".[dev]"
184
+ pytest
185
+ ruff check .
186
+ ```
187
+
188
+ Tests don't need a Bring account: they cover the tools against a fake list
189
+ (merging, catalog names, list lookup, staples), input validation, re-login after
190
+ an expired session, and the OAuth flow (redirect allowlist, client cap, lockout,
191
+ security headers, startup checks).
192
+
193
+ ## License
194
+
195
+ [MIT](https://github.com/vdeabreu/bring-mcp/blob/main/LICENSE)