Bar Assistant MCP Server

An MCP (Model Context Protocol) server for Bar Assistant - manage your home bar shelf and discover cocktails you can make.

Features

• 📋 View ingredients on your bar shelf
• 🍸 See cocktails you can make with what you have
• ➕ Add ingredients to your shelf
• ➖ Remove ingredients from your shelf
• 🔍 Search for ingredients by name
• 🏪 Discover your available bars
• 🧪 Create new ingredients
• 🍹 Create new cocktail recipes
• ✏️ Update existing cocktail recipes

Installation

Using uvx (Recommended)

Run directly with uvx:

uvx --from git+https://github.com/the-real-py/bar-assistant-mcp bar-assistant-mcp \
  https://bar.johnprovost.com/bar/api \
  your_token_here \
  1

Or set environment variables in .env and run:

uvx --from git+https://github.com/the-real-py/bar-assistant-mcp bar-assistant-mcp

Using pip

pip install git+https://github.com/the-real-py/bar-assistant-mcp
bar-assistant-mcp

Configuration

Create a .env file in your project directory:

BAR_ASSISTANT_API_URL=https://bar.johnprovost.com/bar/api
BAR_ASSISTANT_TOKEN=your_bearer_token_here
BAR_ASSISTANT_BAR_ID=1

Or pass them as command-line arguments:

bar-assistant-mcp <api_url> <token> <bar_id>

Getting Your Credentials

1. API URL: Your Bar Assistant instance URL + the API path
   • Standard setup: http://localhost:8000/api
   • Custom setup: Check your reverse proxy configuration (e.g., https://bar.example.com/bar/api)
2. Token: Generate a personal access token from your Bar Assistant profile settings
3. Bar ID: Use the list_bars tool to find your bar ID, or it's usually 1 for your first bar

Important: The BAR_ASSISTANT_BAR_ID is optional. If you don't set it, you can provide the bar_id parameter when calling tools, or use the list_bars tool first to discover your available bars.

Usage with Claude Desktop

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

{
  "mcpServers": {
    "bar-assistant": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/the-real-py/bar-assistant-mcp",
        "bar-assistant-mcp",
        "https://bar.johnprovost.com/bar/api",
        "your_token_here",
        "1"
      ]
    }
  }
}

Or using environment variables:

{
  "mcpServers": {
    "bar-assistant": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/the-real-py/bar-assistant-mcp",
        "bar-assistant-mcp"
      ],
      "env": {
        "BAR_ASSISTANT_API_URL": "https://bar.johnprovost.com/bar/api",
        "BAR_ASSISTANT_TOKEN": "your_token_here",
        "BAR_ASSISTANT_BAR_ID": "1"
      }
    }
  }
}

Available Tools

list_bars

Discover all bars you have access to and get their IDs.

get_shelf_ingredients

List all ingredients on your bar shelf.

Parameters:

• bar_id (optional): Bar ID to query
• page (optional): Page number for pagination

get_shelf_cocktails

See all cocktails you can make with your current ingredients.

Parameters:

• bar_id (optional): Bar ID to query
• page (optional): Page number for pagination

add_ingredients_to_shelf

Add ingredients to your shelf by their IDs.

Parameters:

• ingredient_ids (required): Array of ingredient IDs
• bar_id (optional): Bar ID to update

remove_ingredients_from_shelf

Remove ingredients from your shelf.

Parameters:

• ingredient_ids (required): Array of ingredient IDs
• bar_id (optional): Bar ID to update

search_ingredients

Search for ingredients by name to find their IDs.

Parameters:

• name (required): Ingredient name to search for
• bar_id (optional): Bar ID context

create_ingredient

Create a new ingredient in the bar database. Use this when an ingredient doesn't exist and needs to be created before adding to a cocktail.

Parameters:

• name (required): Name of the ingredient
• strength (optional): Alcohol strength/percentage (e.g., 40 for 40% ABV)
• description (optional): Description of the ingredient
• origin (optional): Origin/country of the ingredient
• color (optional): Hex color code (e.g., '#ffffff')
• parent_ingredient_id (optional): Parent ingredient ID for categorization
• units (optional): Default units for this ingredient (e.g., 'ml', 'oz', 'dash')
• bar_id (optional): Bar ID context

create_cocktail

Create a new cocktail recipe. First use search_ingredients to find ingredient IDs, then use create_ingredient for any missing ingredients.

Parameters:

• name (required): Name of the cocktail
• instructions (required): Step-by-step instructions for making the cocktail
• ingredients (required): Array of ingredients with:
  • ingredient_id (required): ID of the ingredient
  • amount (required): Amount of the ingredient
  • units (optional): Units for the amount (e.g., 'ml', 'oz', 'dash')
  • optional (optional): Whether this ingredient is optional
  • note (optional): Additional note for this ingredient
  • sort (optional): Sort order for the ingredient
• description (optional): Description of the cocktail
• garnish (optional): Garnish for the cocktail
• source (optional): Source/origin of the recipe
• glass_id (optional): ID of the glass type to use
• method_id (optional): ID of the mixing method (shaken, stirred, etc.)
• tags (optional): Array of tags for the cocktail
• bar_id (optional): Bar ID context

Example - Creating a Margarita:

1. search_ingredients(name="tequila") → ID: 45
2. search_ingredients(name="lime juice") → ID: 89  
3. search_ingredients(name="triple sec") → ID: 23
4. create_cocktail(
     name="Margarita",
     instructions="1. Add all ingredients to shaker with ice\n2. Shake well\n3. Strain into salt-rimmed glass",
     ingredients=[
       {"ingredient_id": 45, "amount": 60, "units": "ml"},
       {"ingredient_id": 89, "amount": 30, "units": "ml"},
       {"ingredient_id": 23, "amount": 30, "units": "ml"}
     ],
     garnish="Lime wheel, salt rim"
   )

update_cocktail

Update an existing cocktail recipe. Use this to modify the name, instructions, ingredients, or other details of a cocktail.

Parameters:

• id (required): ID of the cocktail to update
• name (required): Name of the cocktail
• instructions (required): Step-by-step instructions for making the cocktail
• ingredients (required): Array of ingredients with:
  • ingredient_id (required): ID of the ingredient
  • amount (required): Amount of the ingredient
  • units (optional): Units for the amount (e.g., 'ml', 'oz', 'dash')
  • optional (optional): Whether this ingredient is optional
  • note (optional): Additional note for this ingredient
  • sort (optional): Sort order for the ingredient
• description (optional): Description of the cocktail
• garnish (optional): Garnish for the cocktail
• source (optional): Source/origin of the recipe
• glass_id (optional): ID of the glass type to use
• method_id (optional): ID of the mixing method (shaken, stirred, etc.)
• tags (optional): Array of tags for the cocktail
• bar_id (optional): Bar ID context

Resources

• bar://shelf/ingredients - Your bar shelf ingredients
• bar://shelf/cocktails - Cocktails you can make

Development

Clone and install in development mode:

git clone https://github.com/the-real-py/bar-assistant-mcp
cd bar-assistant-mcp
pip install -e .

Troubleshooting

Finding Your API URL

The Bar Assistant API URL depends on your setup:

1. Standard Docker setup: http://localhost:8000/api
2. Custom reverse proxy: Check your nginx/Traefik configuration for the API route
3. Cloud hosted: Usually provided by your hosting service

To verify your API URL is correct, run:

curl -H "Accept: application/json" YOUR_API_URL/server/version

You should get a JSON response with version information.

License

MIT

Links

• Bar Assistant
• Bar Assistant Documentation
• MCP Documentation