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 uses the MCP TypeScript SDK v2 server package to provide an MCP-compliant 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": {
        "BRING_EMAIL": "your_bring_email@example.com",
        "BRING_PASSWORD": "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.

Related MCP server: lista-compras-mcp

💬 Using with ChatGPT via OpenAI Secure MCP Tunnel

OpenAI Secure MCP Tunnel lets ChatGPT reach this STDIO server without exposing it through a public endpoint. The tunnel client itself is provided as a downloadable binary, while bring-mcp can still be launched through npx without a local checkout or installation.

Prerequisites

• Node.js 22 or newer, including npm/npx

• ChatGPT developer-mode access

• Tunnels Read + Use permissions in the relevant OpenAI Platform organization

• A tunnel ID and runtime API key from OpenAI Platform tunnel settings

• The tunnel-client binary, available from the download link in the tunnel settings

When creating the tunnel, associate it with the ChatGPT workspace in which you want to use Bring. Otherwise, it will not appear when creating the ChatGPT connection.

Configure and run the tunnel

Export the tunnel API key and your Bring! credentials in the shell that will run tunnel-client:

export CONTROL_PLANE_API_KEY="sk-..."
export BRING_EMAIL="your_bring_email@example.com"
export BRING_PASSWORD="YOUR_BRING_PASSWORD_HERE"

Create a tunnel profile that starts the latest published bring-mcp package through npx:

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile bring-mcp \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "npx -y bring-mcp@latest"

Validate the configuration, then start the tunnel:

tunnel-client doctor --profile bring-mcp --explain
tunnel-client run --profile bring-mcp

Keep this process running while using the integration. The environment variables above are inherited by the npx-started MCP server.

Connect the tunnel in ChatGPT

1. In ChatGPT, open Settings → Security and login and enable Developer mode.

2. Open ChatGPT Plugins and select the plus button to create a developer-mode app.

3. Enter a name and description, choose Tunnel under Connection, and select the tunnel created above (or enter its tunnel_id).

4. Create the connection and review the 16 discovered Bring! tools.

5. Start a new chat, enable the Bring connection from the tools menu, and try a request such as “Show my Bring shopping lists.”

If ChatGPT cannot discover the server, make sure tunnel-client run is still active, rerun the doctor command, and verify that the tunnel is associated with the correct ChatGPT workspace. Secure MCP Tunnel is intended for private connections and developer-mode testing; publishing a public ChatGPT plugin requires a stable public HTTPS MCP endpoint.

🚀 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 MCP protocol revision 2026-07-28 while continuing to serve legacy 2025 clients

• Publishes tool titles, annotations, concrete input/output schemas, and machine-readable structured results

• Marks tool failures with isError: true so clients can distinguish them from successful calls

• 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 item image from base64-encoded image data (maximum decoded size: 5 MiB)

• 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):

   BRING_EMAIL=your_email@example.com
   BRING_PASSWORD=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 v<version> 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": {
        "BRING_EMAIL": "your_bring_email@example.com",
        "BRING_PASSWORD": "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 and Tools

• @modelcontextprotocol/server: MCP SDK v2 server and STDIO protocol dispatcher

• @modelcontextprotocol/client: Development-only client used for end-to-end protocol compatibility tests

• @modelcontextprotocol/inspector: Run on demand with npx 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.

• ♻️ MAIL and PW remain supported as deprecated aliases for existing installations.

• 🧼 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! 🎉