MCP Server for Bring! Shopping

This project implements a local Model Context Protocol (MCP) server in TypeScript that exposes the functionalities of the Bring! shopping list API. It enables applications like Claude Desktop to interact with your Bring! shopping lists using standardized MCP tools.

The server integrates the bring-shopping npm package for Bring! API access and leverages @modelcontextprotocol/sdk to provide an MCP-compliant server interface.

> Disclaimer:
> This is a personal project. I am not affiliated with Bring! Labs AG in any way.
> This project uses an unofficial Bring! API, which may change or be blocked at any time.
> This could cause the MCP server to stop functioning without prior notice.

---

🧩 Recommended Claude Desktop Configuration

To use this server in Claude Desktop via npx, insert the following into your claude_desktop_config.json file:

{
  "mcpServers": {
    "bring-mcp": {
      "command": "npx",
      "args": ["-y", "bring-mcp@latest"],
      "env": {
        "MAIL": "your_bring_email@example.com",
        "PW": "YOUR_BRING_PASSWORD_HERE"
      }
    }
  }
}

This is the recommended and most portable configuration. It ensures you always use the latest version published to npm without needing local installation.

---

🚀 Features

- Automatic Authentication: No manual login required - authentication happens automatically on first API call
- Exposes Bring! API functions as MCP tools:
- 🧾 Load shopping lists
- 🛒 Get and modify items (add, remove, move)
- 📦 Batch operations (save multiple items, delete multiple items)
- 🖼 Save/remove item images
- 👥 Manage list users
- 🎯 Get default shopping list UUID
- 🌐 Load translations & catalog
- 📨 Retrieve pending invitations
- Communicates via STDIO (for use with Claude Desktop or MCP Inspector)
- Supports Bring! credentials via .env file or injected environment variables

Available Tools

- loadLists: Load all shopping lists from Bring!
- getItems: Get all items from a specific shopping list
- getItemsDetails: Get details for items in a list
- saveItem: Save an item to a shopping list with optional specification
- saveItemBatch: Save multiple items to a shopping list in one operation
- removeItem: Remove an item from a specific shopping list
- moveToRecentList: Move an item to the recently used items list
- deleteMultipleItemsFromList: Delete multiple items from a list by their names
- saveItemImage: Save an image for an item on a shopping list
- removeItemImage: Remove an image from an item
- getAllUsersFromList: Get all users associated with a shopping list
- getUserSettings: Get settings for the authenticated user
- getDefaultList: Get the UUID of the default shopping list (use when user doesn't specify a list)
- loadTranslations: Load translations for the Bring! interface
- loadCatalog: Load the Bring! item catalog
- getPendingInvitations: Get pending invitations to join shopping lists

---

⚙️ Setup and Installation

1. Clone the repo (or obtain the files)

2. Navigate into the project directory:

   cd path/to/bring-mcp
   

3. Install dependencies:

   npm install
   

4. Create .env file (if not injecting ENV directly):

   MAIL=your_email@example.com
   PW=your_password
   

5. Build the project:

   npm run build
   

6. Make script executable (optional on Unix):

   chmod +x build/src/index.js
   

---

🏃 Running the Server

Launch the MCP server with:

node build/src/index.js

If successful, you'll see: MCP server for Bring! API is running on STDIO (on stderr).

---

🧪 Testing with MCP Inspector

1. Ensure npm run build has been executed.
2. Ensure .env with valid credentials exists.
3. Run Inspector:

   npx @modelcontextprotocol/inspector node /ABS/PATH/bring-mcp/build/src/index.js
   

---

🧩 Claude Desktop Integration (Manual Local Setup)

Alternatively, if you prefer a locally built and installed version:

{
  "mcpServers": {
    "mcp-bring": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/bring-mcp/build/src/index.js"],
      "env": {
        "MAIL": "your_bring_email@example.com",
        "PW": "YOUR_BRING_PASSWORD_HERE"
      }
    }
  }
}

---

🔧 Development

Testing

Run tests with:

npm run test

This command runs formatting, linting, and Jest tests with coverage reporting.

For CI testing:

npm run test:ci

Building

Build the project:

npm run build

Key Dependencies

- @modelcontextprotocol/sdk: For MCP server implementation
- @modelcontextprotocol/inspector: For testing and debugging MCP servers
- bring-shopping: Node.js wrapper for the Bring! API
- zod: For schema definition and validation
- dotenv: For managing environment variables

---

✅ Final Notes

- 🔒 Avoid committing your .env file.
- 🧼 Keep credentials out of version control.
- 🛠 MCP Inspector is invaluable for debugging.
- 🔄 Authentication is handled automatically - no manual login required.
- 📦 Use batch operations for efficiency when working with multiple items.

Happy coding with MCP and Bring! 🎉