Skip to main content
Glama

colacloud-mcp

MCP server for COLA Cloud - access US alcohol label data from AI assistants.

Query 2.5M+ Certificate of Label Approval (COLA) records from the TTB (Alcohol and Tobacco Tax and Trade Bureau) directly from Claude, ChatGPT, or other MCP-compatible AI tools.

Installation

# Using uvx (recommended, no install required)
uvx colacloud-mcp

# Or install with pip
pip install colacloud-mcp

Configuration

Claude Desktop

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

{
  "mcpServers": {
    "colacloud": {
      "command": "uvx",
      "args": ["colacloud-mcp"],
      "env": {
        "COLA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Other MCP Clients

Set the COLA_API_KEY environment variable and run:

export COLA_API_KEY="your-api-key-here"
colacloud-mcp

Getting an API Key

  1. Create an account at app.colacloud.us

  2. Go to Dashboard > API Keys

  3. Create a new API key

Free tier includes 500 requests/month.

Available Tools

Tool

Description

search_colas

Search and filter COLA records by brand, product type, origin, dates, ABV

get_cola

Get detailed info for a specific COLA by TTB ID

search_permittees

Search permit holders (alcohol producers/importers)

get_permittee

Get permit holder details with recent COLAs

lookup_barcode

Find COLAs by product barcode (UPC/EAN)

get_api_usage

Check your API usage and rate limits

Example Queries

Once configured, you can ask Claude things like:

  • "Search for Tito's vodka labels"

  • "Find wine labels from Napa Valley approved in 2024"

  • "Look up the product with barcode 080686001010"

  • "Show me recent labels from permit holder CA-I-123"

  • "What craft beers have an IBU over 60?"

Data Available

Each COLA record includes:

  • Basic info: Brand name, product name, product type, origin

  • Dates: Application, approval, expiration dates

  • Label images: Front, back, neck, strip labels (1-2 per record)

  • Extracted data: ABV, volume, barcodes (via OCR/computer vision)

  • AI enrichment: Category, tasting notes, product descriptions

Development

# Clone and install
git clone https://github.com/cola-cloud-us/colacloud-mcp
cd colacloud-mcp
uv sync --dev

# Run locally
export COLA_API_KEY="your-key"
uv run colacloud-mcp

# Run tests
uv run pytest

# Lint
uv run ruff check .

License

MIT

Available Tools

6 tools
get_api_usageA

Check your COLA Cloud API usage and rate limits.

Returns current usage statistics including requests used this month, remaining quota, and rate limit information.

Returns: Usage stats including tier, limits, and current period usage

Inputs: no named parameters. Returns: object

get_colaA

Get detailed information about a specific COLA by its TTB ID.

Returns the full record including all label images, extracted barcodes, and AI-enriched fields like product descriptions, tasting notes, and category classifications.

Args: ttb_id: The TTB (Alcohol and Tobacco Tax and Trade Bureau) ID, e.g., "23001001000001"

Returns: Complete COLA record with images, barcodes, and enrichment data

Inputs: ttb_id (required). Returns: object

get_permitteeB

Get detailed information about a permit holder.

Returns the permittee's company details and their 10 most recent COLAs.

Args: permit_number: The federal permit number, e.g., "NY-I-123"

Returns: Permittee details with recent COLA summaries

Inputs: permit_number (required). Returns: object

lookup_barcodeA

Find COLAs by product barcode (UPC, EAN, etc.).

Barcodes are extracted from label images using computer vision. This tool finds all COLAs that contain a specific barcode, useful for identifying products or tracking label changes over time.

Args: barcode_value: The barcode number (UPC, EAN, etc.), e.g., "012345678905"

Returns: Barcode info and all associated COLAs

Inputs: barcode_value (required). Returns: object

search_colasA

Search and filter COLA (Certificate of Label Approval) records.

COLAs are federal approvals for alcohol product labels in the US. Each record includes brand name, product details, label images, and enriched data like barcodes and AI-extracted features.

Args: q: Full-text search query (searches brand, product name, origin) product_type: Filter by type - "malt beverage", "wine", or "distilled spirits" origin: Filter by country or US state (e.g., "california", "france") brand_name: Filter by brand name (partial match, case-insensitive) approval_date_from: Minimum approval date (YYYY-MM-DD) approval_date_to: Maximum approval date (YYYY-MM-DD) abv_min: Minimum alcohol by volume percentage abv_max: Maximum alcohol by volume percentage page: Page number for pagination (default: 1) per_page: Results per page (default: 20, max: 100)

Returns: Search results with COLA summaries and pagination info

Inputs: q, product_type, origin, brand_name, +6 more. Returns: object

search_permitteesA

Search permit holders (companies authorized to produce/import alcohol).

Permittees are businesses that hold federal permits to manufacture, import, or wholesale alcohol products. Each permittee can have many COLAs.

Args: q: Search by company name (partial match) state: Filter by US state (two-letter code, e.g., "CA", "NY") is_active: Filter by active permit status (true/false) page: Page number for pagination (default: 1) per_page: Results per page (default: 20, max: 100)

Returns: Search results with permittee summaries and pagination info

Inputs: q, state, is_active, page, +1 more. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose targeting different resources and actions within the COLA domain. get_cola retrieves specific records by TTB ID, search_colas performs filtered searches, lookup_barcode finds records by barcode, get_permittee retrieves permit holder details, search_permittees searches permit holders, and get_api_usage checks system usage - there is no functional overlap between these operations.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern (get_api_usage, get_cola, get_permittee, lookup_barcode, search_colas, search_permittees). The verbs 'get', 'lookup', and 'search' are appropriately differentiated based on the operation type, creating a predictable and readable naming convention throughout the set.

    Tool Count5/5

    With 6 tools, this server is well-scoped for its COLA database domain. The count provides comprehensive coverage without bloat - each tool serves a distinct, necessary function for interacting with COLA records, permit holders, and system usage, making the set appropriately sized for the server's purpose.

    Completeness4/5

    The tool set provides excellent coverage for querying and retrieving COLA and permittee data, including search, lookup by various identifiers, and system monitoring. The only minor gap is the absence of write/update operations, but given the domain appears to be a regulatory database (likely read-only), the surface is appropriately complete for typical agent workflows.

    Related MCP Connectors