MCP Server for Bring! Shopping

Bring! 购物清单 MCP 服务

本项目使用 TypeScript 实现了一个本地模型上下文协议（MCP）服务，提供 Bring! 购物清单 API 的功能。它支持 Claude Desktop 等应用通过标准化的 MCP 工具与您的 Bring! 购物清单交互。

该服务集成了 bring-shopping npm 包以访问 Bring! API，并使用 MCP TypeScript SDK v2 服务包提供符合 MCP 规范的接口。

免责声明：
这是一个个人项目。我与 Bring! Labs AG 没有任何关联。
本项目使用的是非官方 Bring! API，它可能随时变更或被屏蔽。
这可能导致 MCP 服务在没有事先通知的情况下停止运行。

---

🧩 推荐的 Claude Desktop 配置

要在 Claude Desktop 中通过 npx 使用此服务，请将以下内容插入 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "bring-mcp": {
      "command": "npx",
      "args": ["-y", "bring-mcp@latest"],
      "env": {
        "BRING_EMAIL": "[email protected]",
        "BRING_PASSWORD": "YOUR_BRING_PASSWORD_HERE"
      }
    }
  }
}

这是推荐且最具可移植性的配置。它确保您始终使用发布到 npm 的最新版本，无需本地安装。

---

💬 通过 OpenAI Secure MCP Tunnel 与 ChatGPT 搭配使用

OpenAI Secure MCP Tunnel 可让 ChatGPT 访问此 STDIO 服务，而无需通过公共端点公开服务。隧道客户端本身以可下载的二进制文件形式提供，而 bring-mcp 仍可通过 npx 启动，无需本地检出或安装。

前提条件

• Node.js 22 或更高版本，包括 npm/npx
• ChatGPT 开发者模式访问权限
• 相关 OpenAI Platform 组织中的 Tunnels Read + Use 权限
• 来自 OpenAI Platform 隧道设置的隧道 ID 和运行时 API 密钥
• tunnel-client 二进制文件，可通过隧道设置中的下载链接获取

创建隧道时，请将其关联到您希望使用 Bring 的 ChatGPT 工作区。否则，创建 ChatGPT 连接时将看不到该隧道。

配置并运行隧道

在将运行 tunnel-client 的 shell 中导出隧道 API 密钥和 Bring! 凭据：

export CONTROL_PLANE_API_KEY="sk-..."
export BRING_EMAIL="[email protected]"
export BRING_PASSWORD="YOUR_BRING_PASSWORD_HERE"

创建隧道配置文件，通过 npx 启动最新发布的 bring-mcp 包：

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

验证配置，然后启动隧道：

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

使用集成时，请保持此进程运行。上述环境变量会由通过 npx 启动的 MCP 服务继承。

在 ChatGPT 中连接隧道

1. 在 ChatGPT 中，打开 设置 → 安全与登录，然后启用开发者模式。
2. 打开 ChatGPT 插件，并选择加号按钮来创建开发者模式应用。
3. 输入名称和描述，在连接下选择隧道，然后选择上方创建的隧道（或输入其 tunnel_id）。
4. 创建连接并查看发现的 16 个 Bring! 工具。
5. 开始新聊天，从工具菜单启用 Bring 连接，并尝试发送类似“显示我的 Bring 购物清单”的请求。

如果 ChatGPT 无法发现服务，请确保 tunnel-client run 仍在运行，重新执行 doctor 命令，并确认隧道已关联到正确的 ChatGPT 工作区。Secure MCP Tunnel 用于私有连接和开发者模式测试；发布公共 ChatGPT 插件则需要稳定的公共 HTTPS MCP 端点。

---

🚀 功能

• 自动身份验证：无需手动登录，首次调用 API 时会自动完成身份验证
• 将 Bring! API 功能作为 MCP 工具提供：
  • 🧾 加载购物清单
  • 🛒 获取和修改商品（添加、移除、移动）
  • 📦 批量操作（保存多个商品、删除多个商品）
  • 🖼 保存/移除商品图片
  • 👥 管理清单用户
  • 🎯 获取默认购物清单 UUID
  • 🌐 加载翻译和目录
  • 📨 获取待处理的邀请
• 通过 STDIO 通信（用于 Claude Desktop 或 MCP Inspector）
• 支持 MCP 协议修订版 2026-07-28，同时继续为旧版 2025 客户端提供服务
• 提供工具标题、注释、具体的输入/输出模式以及机器可读的结构化结果
• 使用 isError: true 标记工具失败，以便客户端区分失败调用和成功调用
• 支持通过 .env 文件或注入的环境变量提供 Bring! 凭据

可用工具

• loadLists：加载 Bring! 中的所有购物清单
• getItems：获取指定购物清单中的所有商品
• getItemsDetails：获取清单中商品的详情
• saveItem：将商品保存到购物清单，可选填写规格
• saveItemBatch：一次操作将多个商品保存到购物清单
• removeItem：从指定购物清单中移除商品
• moveToRecentList：将商品移至最近使用的商品清单
• deleteMultipleItemsFromList：按名称从清单中删除多个商品
• saveItemImage：从 Base64 编码的图片数据中保存商品图片（解码后最大大小：5 MiB）
• removeItemImage：移除商品图片
• getAllUsersFromList：获取与购物清单关联的所有用户
• getUserSettings：获取已验证用户的设置
• getDefaultList：获取默认购物清单的 UUID（用户未指定清单时使用）
• loadTranslations：加载 Bring! 界面的翻译
• loadCatalog：加载 Bring! 商品目录
• getPendingInvitations：获取加入购物清单的待处理邀请

---

⚙️ 设置与安装

1. 克隆代码库（或获取文件）

2. 进入项目目录：

   cd path/to/bring-mcp
   

3. 安装依赖项：

   npm install
   

4. 创建 .env 文件（如果未直接注入环境变量）：

   [email protected]
   BRING_PASSWORD=your_password
   

5. 构建项目：

   npm run build
   

6. 使脚本可执行（Unix 系统上可选）：

   chmod +x build/src/index.js
   

---

🏃 运行服务

使用以下命令启动 MCP 服务：

node build/src/index.js

如果成功，你会看到：MCP server for Bring! API v<version> is running on STDIO（输出到 stderr）。

---

🧪 使用 MCP Inspector 测试

1. 确保已执行 npm run build。

2. 确保 .env 中包含有效凭据。

3. 运行 Inspector：

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

---

🧩 Claude Desktop 集成（手动本地设置）

或者，如果你更倾向于使用本地构建和安装的版本：

{
  "mcpServers": {
    "mcp-bring": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/bring-mcp/build/src/index.js"],
      "env": {
        "BRING_EMAIL": "[email protected]",
        "BRING_PASSWORD": "YOUR_BRING_PASSWORD_HERE"
      }
    }
  }
}

---

🔧 开发

测试

使用以下命令运行测试：

npm run test

此命令会运行格式检查、代码检查和 Jest 测试，并生成覆盖率报告。

用于 CI 测试：

npm run test:ci

构建

构建项目：

npm run build

主要依赖项和工具

• @modelcontextprotocol/server：MCP SDK v2 服务端和 STDIO 协议分发器
• @modelcontextprotocol/client：仅用于开发的客户端，用于端到端协议兼容性测试
• @modelcontextprotocol/inspector：按需使用 npx 运行，用于测试和调试 MCP 服务
• bring-shopping：Bring! API 的 Node.js 封装
• zod：用于模式定义和验证
• dotenv：用于管理环境变量

✅ 最后说明

• 🔒 避免提交你的 .env 文件。
• ♻️ 对于现有安装，仍支持将 MAIL 和 PW 用作已弃用的别名。
• 🧼 不要将凭据纳入版本控制。
• 🛠 MCP Inspector 对调试非常有用。
• 🔄 身份验证会自动处理，无需手动登录。
• 📦 处理多个项目时，请使用批量操作以提高效率。

祝你使用 MCP 和 Bring 编码愉快！🎉