MCP Server for Bring! Shopping

Interactúa con la API de listas de compras de Bring! a través de un servidor MCP local.

GitHub
27
Prueba este MCPPatrocinado

Documentación

Servidor MCP para Bring! Shopping

bring-mcp

Este proyecto implementa un servidor local de Protocolo de Contexto de Modelo (MCP) en TypeScript que expone las funcionalidades de la API de listas de compras de Bring!. Permite que aplicaciones como Claude Desktop interactúen con tus listas de compras de Bring! utilizando herramientas MCP estandarizadas.

El servidor integra el paquete npm bring-shopping para el acceso a la API de Bring! y utiliza el paquete de servidor MCP TypeScript SDK v2 para proporcionar una interfaz compatible con MCP.

Aviso:
Este es un proyecto personal. No estoy afiliado con Bring! Labs AG de ninguna manera.
Este proyecto utiliza una API no oficial de Bring!, que puede cambiar o ser bloqueada en cualquier momento.
Esto podría causar que el servidor MCP deje de funcionar sin previo aviso.

🧩 Configuración recomendada para Claude Desktop

Para usar este servidor en Claude Desktop a través de npx, inserta lo siguiente en tu archivo claude_desktop_config.json:

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

Esta es la configuración recomendada y más portátil. Garantiza que siempre uses la versión más reciente publicada en npm sin necesidad de instalación local.

💬 Uso con ChatGPT a través del túnel seguro MCP de OpenAI

OpenAI Secure MCP Tunnel permite que ChatGPT acceda a este servidor STDIO sin exponerlo a través de un endpoint público. El cliente del túnel se proporciona como un binario descargable, mientras que bring-mcp se puede iniciar a través de npx sin necesidad de clonar el repositorio ni instalar localmente.

Requisitos previos

  • Node.js 22 o superior, incluyendo npm/npx
  • Acceso al modo de desarrollador de ChatGPT
  • Permisos de Tunnels Read + Use en la organización relevante de la Plataforma OpenAI
  • Un ID de túnel y una clave API de ejecución desde configuración de túneles de la Plataforma OpenAI
  • El binario tunnel-client, disponible desde el enlace de descarga en la configuración del túnel

Al crear el túnel, asócialo con el espacio de trabajo de ChatGPT en el que deseas usar Bring!. De lo contrario, no aparecerá al crear la conexión de ChatGPT.

Configurar y ejecutar el túnel

Exporta la clave API del túnel y tus credenciales de Bring! en el shell que ejecutará tunnel-client:

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

Crea un perfil de túnel que inicie la última versión publicada del paquete bring-mcp a través de npx:

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

Valida la configuración y luego inicia el túnel:

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

Mantén este proceso en ejecución mientras usas la integración. Las variables de entorno anteriores son heredadas por el servidor MCP iniciado por npx.

Conectar el túnel en ChatGPT

  1. En ChatGPT, abre Configuración → Seguridad e inicio de sesión y habilita Modo de desarrollador.
  2. Abre ChatGPT Plugins y selecciona el botón de más para crear una aplicación en modo de desarrollador.
  3. Ingresa un nombre y una descripción, elige Túnel en Conexión y selecciona el túnel creado anteriormente (o ingresa su tunnel_id).
  4. Crea la conexión y revisa las 16 herramientas de Bring! descubiertas.
  5. Inicia un nuevo chat, habilita la conexión de Bring! desde el menú de herramientas y prueba una solicitud como "Muestra mis listas de compras de Bring!".

Si ChatGPT no puede descubrir el servidor, asegúrate de que tunnel-client run siga activo, vuelve a ejecutar el comando doctor y verifica que el túnel esté asociado con el espacio de trabajo correcto de ChatGPT. Secure MCP Tunnel está diseñado para conexiones privadas y pruebas en modo de desarrollador; publicar un plugin público de ChatGPT requiere un endpoint MCP HTTPS público y estable.

🚀 Características

  • Autenticación automática: No se requiere inicio de sesión manual: la autenticación ocurre automáticamente en la primera llamada a la API
  • Expone las funciones de la API de Bring! como herramientas MCP:
    • 🧾 Cargar listas de compras
    • 🛒 Obtener y modificar artículos (agregar, eliminar, mover)
    • 📦 Operaciones por lotes (guardar múltiples artículos, eliminar múltiples artículos)
    • 🖼 Guardar/eliminar imágenes de artículos
    • 👥 Gestionar usuarios de listas
    • 🎯 Obtener el UUID de la lista de compras predeterminada
    • 🌐 Cargar traducciones y catálogo
    • 📨 Recuperar invitaciones pendientes
  • Se comunica a través de STDIO (para usar con Claude Desktop o MCP Inspector)
  • Soporta la revisión del protocolo MCP 2026-07-28 mientras continúa sirviendo a clientes heredados de 2025
  • Publica títulos de herramientas, anotaciones, esquemas de entrada/salida concretos y resultados estructurados legibles por máquina
  • Marca fallos de herramientas con isError: true para que los clientes puedan distinguirlos de llamadas exitosas
  • Soporta credenciales de Bring! a través del archivo .env o variables de entorno inyectadas

Herramientas disponibles

  • loadLists: Cargar todas las listas de compras de Bring!
  • getItems: Obtener todos los artículos de una lista de compras específica
  • getItemsDetails: Obtener detalles de los artículos en una lista
  • saveItem: Guardar un artículo en una lista de compras con especificación opcional
  • saveItemBatch: Guardar múltiples artículos en una lista de compras en una sola operación
  • removeItem: Eliminar un artículo de una lista de compras específica
  • moveToRecentList: Mover un artículo a la lista de artículos usados recientemente
  • deleteMultipleItemsFromList: Eliminar múltiples artículos de una lista por sus nombres
  • saveItemImage: Guardar una imagen de artículo desde datos de imagen codificados en base64 (tamaño máximo decodificado: 5 MiB)
  • removeItemImage: Eliminar una imagen de un artículo
  • getAllUsersFromList: Obtener todos los usuarios asociados con una lista de compras
  • getUserSettings: Obtener la configuración del usuario autenticado
  • getDefaultList: Obtener el UUID de la lista de compras predeterminada (usar cuando el usuario no especifica una lista)
  • loadTranslations: Cargar traducciones para la interfaz de Bring!
  • loadCatalog: Cargar el catálogo de artículos de Bring!
  • getPendingInvitations: Obtener invitaciones pendientes para unirse a listas de compras

⚙️ Configuración e instalación

  1. Clona el repositorio (u obtén los archivos)

  2. Navega al directorio del proyecto:

    cd path/to/bring-mcp

  3. Instala las dependencias:

    npm install

  4. Crea el archivo .env (si no inyectas variables ENV directamente):

    BRING_EMAIL=your_email@example.com
BRING_PASSWORD=your_password

  5. Compila el proyecto:

    npm run build

  6. Haz que el script sea ejecutable (opcional en Unix):

    chmod +x build/src/index.js

🏃 Ejecutar el servidor

Inicia el servidor MCP con:

node build/src/index.js

Si tiene éxito, verás: MCP server for Bring! API v<version> is running on STDIO (en stderr).

🧪 Pruebas con MCP Inspector

  1. Asegúrate de que npm run build se haya ejecutado.

  2. Asegúrate de que .env con credenciales válidas exista.

  3. Ejecuta Inspector:

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

🧩 Integración con Claude Desktop (Configuración local manual)

Alternativamente, si prefieres una versión compilada e instalada localmente:

{
  "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"
      }
    }
  }
}

🔧 Desarrollo

Pruebas

Ejecuta las pruebas con:

npm run test

Este comando ejecuta formato, linting y pruebas de Jest con informe de cobertura.

Para pruebas de CI:

npm run test:ci

Compilación

Compila el proyecto:

npm run build

Dependencias y herramientas clave

  • @modelcontextprotocol/server: Servidor MCP SDK v2 y despachador de protocolo STDIO
  • @modelcontextprotocol/client: Cliente solo para desarrollo utilizado en pruebas de compatibilidad de protocolo de extremo a extremo
  • @modelcontextprotocol/inspector: Se ejecuta bajo demanda con npx para probar y depurar servidores MCP
  • bring-shopping: Envoltorio de Node.js para la API de Bring!
  • zod: Para definición y validación de esquemas
  • dotenv: Para gestionar variables de entorno

✅ Notas finales

  • 🔒 Evita confirmar tu archivo .env.
  • ♻️ MAIL y PW siguen siendo compatibles como alias obsoletos para instalaciones existentes.
  • 🧼 Mantén las credenciales fuera del control de versiones.
  • 🛠 MCP Inspector es invaluable para depurar.
  • 🔄 La autenticación se maneja automáticamente: no se requiere inicio de sesión manual.
  • 📦 Usa operaciones por lotes para mayor eficiencia al trabajar con múltiples artículos.

¡Feliz codificación con MCP y Bring! 🎉