Bravova MCP Server

A Go-based MCP (Model Context Protocol) server that exposes the Bravova Superbravo grocery delivery API as tools for LLMs like Claude.

Features

• 36 MCP Tools covering the full Bravova API:
  • 7 public catalog tools (sections, articles, search)
  • 2 authentication tools (login, logout)
  • 7 cart tools (get, add, bulk add, update, remove, clear, count)
  • 10 favorites & lists tools (favorites CRUD, shopping lists CRUD, bulk operations)
  • 10 other customer tools (addresses, orders, order details, repeat order, loyalty, recommendations)
• Auto-login via environment variables
• stdio transport for easy integration with Claude Desktop and other MCP clients
• Standard library only - no external dependencies

Installation

Build from source

cd bravova-mcp
go build -o bravova-mcp ./cmd/bravova-mcp

Usage

Running the server

./bravova-mcp

The server supports login via the login tool, or auto-login via environment variables.

Claude Desktop Configuration

Add to your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

Option 1: Using credentials (auto-login)

{
  "mcpServers": {
    "bravova": {
      "command": "/path/to/bravova-mcp",
      "env": {
        "BRAVOVA_USERNAME": "your-cedula",
        "BRAVOVA_PASSWORD": "your-password"
      }
    }
  }
}

Option 2: Using a pre-existing auth token

{
  "mcpServers": {
    "bravova": {
      "command": "/path/to/bravova-mcp",
      "env": {
        "BRAVOVA_AUTH_TOKEN": "your-auth-token",
        "BRAVOVA_STORE_ID": "1008"
      }
    }
  }
}

With credentials configured, the MCP auto-logs in on startup and the store ID is auto-detected from your delivery address. When using a token directly, set BRAVOVA_STORE_ID manually for correct pricing.

Environment Variables

Authentication priority:

1. BRAVOVA_AUTH_TOKEN - use directly if set
2. BRAVOVA_USERNAME + BRAVOVA_PASSWORD - auto-login on startup
3. Neither - use the login tool manually

Store ID behavior:

• With login (username/password): store ID is auto-detected from your delivery address
• With token only: set BRAVOVA_STORE_ID to get correct pricing (e.g., 1008)
• If not set: tools like search_articles won't return prices unless you pass storeId explicitly

Available Tools

Public Catalog Tools (no auth required)

Authentication Tools

Cart Tools (auth required)

Favorites Tools (auth required)

Shopping Lists Tools (auth required)

Other Customer Tools (auth required)

Testing

Test initialize and tools/list

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | ./bravova-mcp
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | ./bravova-mcp

Test a public endpoint

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"list_sections","arguments":{}}}' | ./bravova-mcp

Test search

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_articles","arguments":{"query":"leche"}}}' | ./bravova-mcp

Test login

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"login","arguments":{"username":"YOUR_CEDULA","password":"YOUR_PASSWORD"}}}' | ./bravova-mcp

Project Structure

bravova-mcp/
├── cmd/
│   └── bravova-mcp/
│       └── main.go              # Entry point
├── internal/
│   ├── api/
│   │   ├── client.go            # HTTP client
│   │   ├── models.go            # Data models
│   │   ├── articles.go          # Article endpoints
│   │   ├── sections.go          # Section endpoints
│   │   ├── cart.go              # Cart endpoints
│   │   ├── orders.go            # Order endpoints
│   │   ├── auth.go              # Auth endpoints
│   │   ├── customer.go          # Customer endpoints (favorites, addresses, etc.)
│   │   └── lists.go             # Shopping lists endpoints
│   ├── mcp/
│   │   ├── server.go            # MCP protocol handler
│   │   ├── tools.go             # Tool definitions
│   │   └── types.go             # MCP protocol types
│   └── transport/
│       └── stdio.go             # stdio transport
├── go.mod
└── README.md

Future Features (Nice to Have)

• Streamable HTTP transport - Add HTTP transport with streaming support as per MCP spec (SSE transport is legacy)
• Auto re-login on token expiry - Detect auth failures, automatically re-login if credentials are available, retry the failed request, and notify the user that session was refreshed
• Token persistence - Save token to ~/.bravova-token on successful login, load on startup to avoid re-authentication
• Token expiry detection - Proactively refresh token before it expires

Disclaimer

This project is unofficial and is not affiliated with, endorsed by, or connected to Supermercados Bravo or any of its subsidiaries or affiliates.

This software interacts with Supermercados Bravo's API in a manner that may violate their Terms of Service. Use of this software is at your own risk. The author assumes no responsibility for:

• Account suspension or termination
• Any legal action taken by Supermercados Bravo
• API changes that break functionality
• Data loss or other damages

This project is provided for educational and personal use only. By using this software, you acknowledge that you understand these risks and accept full responsibility for your usage.

License

MIT - See LICENSE for details.