colacloud-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@colacloud-mcp Find recent wine labels from Napa Valley"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-mcpConfiguration
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-mcpGetting an API Key
Create an account at app.colacloud.us
Go to Dashboard > API Keys
Create a new API key
Free tier includes 500 requests/month.
Available Tools
Tool | Description |
| Search and filter COLA records by brand, product type, origin, dates, ABV |
| Get detailed info for a specific COLA by TTB ID |
| Search permit holders (alcohol producers/importers) |
| Get permit holder details with recent COLAs |
| Find COLAs by product barcode (UPC/EAN) |
| 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 toolsget_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
Scored across 6 tools
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.
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.
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.
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
Search US TTB alcohol label approvals, permittees and processing times. Read-only; account required.
Search and export FDA drug labels by brand name, generic ingredient, or UNII code.
Check products against FDA food, drug and device recalls; drug labels, NDC, 510(k) via openFDA
Claims-based knowledge base for no/low ABV specialty beverages (producers, beverages, people).