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

Variable	Description
BRAVOVA_AUTH_TOKEN	Pre-existing auth token (highest priority)
BRAVOVA_USERNAME	Cedula for auto-login
BRAVOVA_PASSWORD	Password for auto-login
BRAVOVA_STORE_ID	Default store ID for pricing/availability

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)

Tool	Description
list_sections	List all product categories/sections
get_section	Get details of a specific section
list_articles	List products with optional filters
get_article	Get detailed product information
search_articles	Search products by name
search_suggestions	Get search autocomplete suggestions
check_auth	Validate an authentication token

Authentication Tools

Tool	Description
login	Authenticate with username (cedula) and password
logout	Log out and invalidate the session

Cart Tools (auth required)

Tool	Description
get_cart	Get shopping cart contents
get_cart_count	Get number of items in cart
add_to_cart	Add an article to the cart
bulk_add_to_cart	Add multiple articles to cart at once
update_cart_quantity	Update quantity of a cart item
remove_from_cart	Remove an item from the cart
clear_cart	Remove multiple items from the cart

Favorites Tools (auth required)

Tool	Description
check_favorite	Check if a product is favorited
add_favorite	Add a product to favorites
remove_favorite	Remove a product from favorites
list_favorites	List all favorite products

Shopping Lists Tools (auth required)

Tool	Description
list_user_lists	List user's shopping lists
create_user_list	Create a new shopping list
get_user_list	Get a list with its articles
update_user_list	Rename a shopping list
delete_user_list	Delete a shopping list
add_article_to_list	Add an article to a list
remove_article_from_list	Remove an article from a list
bulk_remove_articles_from_list	Remove multiple articles from a list

Other Customer Tools (auth required)

Tool	Description
register_device	Register device for push notifications
list_addresses	List saved delivery addresses
list_orders	List order history
get_order	Get detailed order information
repeat_order	Add items from a previous order to cart
get_loyalty_info	Get Bravísima loyalty program info
get_most_purchased	Get most purchased items
get_home_recommendations	Get personalized recommendations

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.