Bar Assistant MCP Server
The Bar Assistant MCP Server allows you to manage your home bar inventory and discover cocktails through integration with the Bar Assistant platform.
Inventory Management: View all ingredients on your bar shelf with detailed information, add or remove ingredients by their IDs, and access shelf contents as resources.
Cocktail Discovery & Creation: See which cocktails you can make with your current ingredients, create new cocktail recipes with ingredients, instructions, garnishes, and metadata, and update existing recipes.
Ingredient Management: Search for ingredients by name to find their IDs, and create custom ingredients with details like strength, origin, color, and description.
Bar Management: Discover and switch between multiple bars you have access to, with context-aware operations supporting a default bar ID or specific bar selection.
Navigation: Browse through large lists of ingredients and cocktails with pagination support.
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., "@Bar Assistant MCP Server what cocktails can I make with my current ingredients?"
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.
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
Related MCP server: Cocktails MCP
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 \
1Or set environment variables in .env and run:
uvx --from git+https://github.com/the-real-py/bar-assistant-mcp bar-assistant-mcpUsing pip
pip install git+https://github.com/the-real-py/bar-assistant-mcp
bar-assistant-mcpConfiguration
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=1Or pass them as command-line arguments:
bar-assistant-mcp <api_url> <token> <bar_id>Getting Your Credentials
API URL: Your Bar Assistant instance URL + the API path
Standard setup:
http://localhost:8000/apiCustom setup: Check your reverse proxy configuration (e.g.,
https://bar.example.com/bar/api)
Token: Generate a personal access token from your Bar Assistant profile settings
Bar ID: Use the
list_barstool to find your bar ID, or it's usually1for 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 querypage(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 querypage(optional): Page number for pagination
add_ingredients_to_shelf
Add ingredients to your shelf by their IDs.
Parameters:
ingredient_ids(required): Array of ingredient IDsbar_id(optional): Bar ID to update
remove_ingredients_from_shelf
Remove ingredients from your shelf.
Parameters:
ingredient_ids(required): Array of ingredient IDsbar_id(optional): Bar ID to update
search_ingredients
Search for ingredients by name to find their IDs.
Parameters:
name(required): Ingredient name to search forbar_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 ingredientstrength(optional): Alcohol strength/percentage (e.g., 40 for 40% ABV)description(optional): Description of the ingredientorigin(optional): Origin/country of the ingredientcolor(optional): Hex color code (e.g., '#ffffff')parent_ingredient_id(optional): Parent ingredient ID for categorizationunits(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 cocktailinstructions(required): Step-by-step instructions for making the cocktailingredients(required): Array of ingredients with:ingredient_id(required): ID of the ingredientamount(required): Amount of the ingredientunits(optional): Units for the amount (e.g., 'ml', 'oz', 'dash')optional(optional): Whether this ingredient is optionalnote(optional): Additional note for this ingredientsort(optional): Sort order for the ingredient
description(optional): Description of the cocktailgarnish(optional): Garnish for the cocktailsource(optional): Source/origin of the recipeglass_id(optional): ID of the glass type to usemethod_id(optional): ID of the mixing method (shaken, stirred, etc.)tags(optional): Array of tags for the cocktailbar_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 updatename(required): Name of the cocktailinstructions(required): Step-by-step instructions for making the cocktailingredients(required): Array of ingredients with:ingredient_id(required): ID of the ingredientamount(required): Amount of the ingredientunits(optional): Units for the amount (e.g., 'ml', 'oz', 'dash')optional(optional): Whether this ingredient is optionalnote(optional): Additional note for this ingredientsort(optional): Sort order for the ingredient
description(optional): Description of the cocktailgarnish(optional): Garnish for the cocktailsource(optional): Source/origin of the recipeglass_id(optional): ID of the glass type to usemethod_id(optional): ID of the mixing method (shaken, stirred, etc.)tags(optional): Array of tags for the cocktailbar_id(optional): Bar ID context
Resources
bar://shelf/ingredients- Your bar shelf ingredientsbar://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:
Standard Docker setup:
http://localhost:8000/apiCustom reverse proxy: Check your nginx/Traefik configuration for the API route
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/versionYou should get a JSON response with version information.
License
MIT
Links
Available Tools
6 toolsadd_ingredients_to_shelfC
Add ingredients to your bar shelf by their IDs
Inputs: ingredient_ids (required), bar_id.
get_shelf_cocktailsB
Get all cocktails you can make with ingredients on your bar shelf
Inputs: bar_id, page.
get_shelf_ingredientsB
Get all ingredients currently on your bar shelf with detailed information
Inputs: bar_id, page.
list_barsB
List all bars you have access to and get their IDs
Inputs: no named parameters.
remove_ingredients_from_shelfC
Remove ingredients from your bar shelf by their IDs
Inputs: ingredient_ids (required), bar_id.
search_ingredientsC
Search for ingredients by name to find their IDs
Inputs: name (required), bar_id.
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 with no overlap: managing shelf ingredients (add/remove/get), searching for ingredients, listing bars, and getting cocktails from the shelf. The actions and targets are well-defined, making misselection unlikely.
All tools follow a consistent verb_noun pattern with snake_case (e.g., add_ingredients_to_shelf, get_shelf_cocktails). The naming is predictable and readable throughout the set, with no deviations in style.
With 6 tools, this server is well-scoped for a bar assistant domain. Each tool earns its place by covering core operations like ingredient management, cocktail discovery, and bar listing, without being too sparse or bloated.
The tool set covers key workflows: CRUD for shelf ingredients (add, remove, get), ingredient search, bar listing, and cocktail generation. A minor gap is the lack of tools for directly managing cocktails or bars (e.g., create/delete bars), but agents can work around this with the provided operations.
Related MCP Connectors
Cocktail recipes and an exact ingredient finder: what can I mix with what I have at home?
Cocktails from the bottles you own: recipes, bar terms, similar drinks, low and zero-proof picks.
Cocktails you can make from bottles you already have, full recipes, and the best next bottle to add.
Learn-to-cook app: assistants read and change recipes, meal plan, groceries and pantry.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables intelligent cocktail discovery and recipe retrieval from Bar Assistant instances with natural language search, similarity matching, batch processing, and ingredient analysis capabilities.33MIT
- AlicenseNot gradedqualityCmaintenanceEnables searching for cocktail recipes by name, ingredient, or randomly, and retrieving full cocktail details including ingredients, measurements, and instructions via TheCocktailDB API.94 npmMIT
- AlicenseBqualityCmaintenanceMCP server for Bar Assistant that enables searching cocktails, managing ingredients, shelves, shopping lists, and collections via natural language.41MIT
- FlicenseAqualityCmaintenanceEnables local drink inventory management, cocktail recipe retrieval, and food pairing recommendations through MCP.10-