The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Bring Photo MCP listing page.
English | Deutsch
Turn product photos into Bring! shopping-list items.
Show your AI agent a package, label, or product photo and say: “Add this to my shopping list.” Bring Photo MCP lets the agent identify the product, match it with the Bring! catalog, select the right category and icon, attach the photo, and add the verified result to your Bring! list.
It also provides the usual list operations—searching, adding, checking, moving, copying, and removing items—but the photo-first workflow is the point: less typing, fewer ambiguous product names, and the original product image directly on the list.
Bring Photo MCP is a local, agent-neutral TypeScript MCP server. The executable stdio entrypoint starts only with locally validated environment variables; this repository contains no Hermes or client runtime configuration.
Requirements: Node.js 20+ and npm.
The official MCP TypeScript SDK (@modelcontextprotocol/sdk) is used. npm start builds the project and starts src/index.ts as a stdio server. Startup validates the configuration and authenticates with Bring only afterwards; this repository intentionally contains no Hermes or client runtime configuration.
The package is prepared for public npm publication, constrained by an explicit files allowlist, and includes a bring-photo-mcp stdio binary entrypoint. The public thin-skill guidance is in SKILL.md; tested client templates are in docs/MCP-CLIENT-CONFIGURATION.md. Migration and rollback without runtime cutover are specified in docs/MIGRATION-ROLLBACK.md.
Never commit .env with real values. The configuration model expects:
BRING_ENV=test|prodBRING_EMAIL, BRING_PASSWORDBRING_DEFAULT_LISTBRING_ALLOWED_LISTS (comma-separated)BRING_LOCALE (default de-DE)BRING_TEST_ITEM_PREFIX (default MCP-TEST-)BRING_TEST_SECOND_LIST exclusively for the multi-list E2Esrc/config.ts validates the values. In PROD, the service accepts only allowlisted lists; the production runtime must additionally point to a pinned release tag. TEST uses a dedicated allowlisted list and temporary prefixed test items only.
npm run test:e2e is deliberately not part of npm test and was not run here. It starts only with a fully configured environment and rejects anything other than BRING_ENV=test. BRING_ALLOWED_LISTS must contain exactly BRING_DEFAULT_LIST; with BRING_TEST_SECOND_LIST, it must contain exactly both named configured TEST lists. A non-empty BRING_TEST_ITEM_PREFIX is required.
The harness creates two synthetic PNG files in the temporary directory, verifies add/read-back as well as photo replace/remove, and removes all of its own prefixed items in finally, followed by an absence check. Copy, move, and multi-list operations run only with an explicit BRING_TEST_SECOND_LIST; without it, the harness reports an honest skip.
src/bring-adapter.ts: deterministic Bring gateway interface and HTTP protocol adapter. Legacy item bodies are generated only with URLSearchParams; details are read through bringlists/{listUuid}/details; the catalog is loaded from https://web.getbring.com/locale/catalog.{locale}.json; detail metadata uses ISO-8859-1 multipart; photos use native FormData with the imageData field. An explicit transferImage gateway capability downloads source image bytes without Bring authentication and uploads them only to the target.src/bring-service.ts: business rules, list allowlisting, classification and duplicate rules, read-back verification, copy-before-delete for moves, and per-list results.src/mcp-server.ts: 15 Zod-validated MCP tools; no transport layer.src/redaction.ts: redacts password/token fields, UUID-like IDs, and local paths from error text.Write operations are successful only after the item and detail have been read again. The detail must contain a UUID, userIconItemId, and userSectionId; photos additionally require imageUrl. Broken/orphan details are not used unless itemId matches exactly.
Read: bring_list_lists, bring_list_items, bring_search_catalog, bring_list_categories, bring_suggest_classification, bring_get_item.
Write: bring_add_item, bring_attach_photo, bring_replace_photo, bring_remove_photo, bring_copy_item, bring_move_item, bring_check_item, bring_uncheck_item, bring_remove_item.
bring_add_item always requires icon_item_id and category_id; both must match within the loaded catalog. The default for duplicate_policy is fail; update_exact changes only the exact same identity. Multi-list calls always return one result per target list and use status: "partial" for partial failures.
CONFIGURATION, LIST_NOT_ALLOWED, LIST_NOT_FOUND, ITEM_NOT_FOUND, INVALID_CLASSIFICATION, DUPLICATE_AMBIGUOUS, VERIFICATION_FAILED, UPSTREAM_FAILURE, IMAGE_INVALID, CLASSIFICATION_UNCERTAIN.
Error text contains no credentials, UUIDs, or image paths.
This project was developed with AI-assisted coding and documentation tools under human direction and review. Its automated tests, isolated live E2E checks, and release artifacts were independently verified before publication. Thomas Schnuecker remains the project maintainer and is responsible for releases.
Credentials, real list UUIDs, and product photos do not belong in Git, fixtures, or logs. This repository triggers no login or live operation. The existing bring-safe solution remains unchanged as the rollback until an explicitly approved cutover.
TEST E2E and the eight-photo regression are intentionally not active automatically: they require an approved dedicated TEST list, temporary prefixed items, and supplied test images. Afterwards, remove every generated TEST item and photo through read-back and verify their absence.