# PunkAPI MCP > PunkAPI lets you search BrewDog's entire catalog of craft beers. Find brews by style, ABV range, hop variety, bitterness level, or even what they pair well with. Whether you need a light session beer for brunch or a bitter IPA for dinner, this server gives your AI client all the filtering tools it needs to narrow down thousands of options fast. ## Overview - **Category:** productivity - **Price:** Free - **Tags:** craft-beer, beverage-data, food-pairing, catalog-search, api-integration ## Description This server gives your AI client total access to BrewDog's entire beer catalog, so you don't have to dig through thousands of pages yourself. You just talk to it naturally and let the agent do the heavy lifting. You wanna find a specific brew? You can use `get_all_beers` to search everything at once. Just drop in filters like names, how much booze it has (ABV), the bitterness level (IBU), what malts are involved, or even what food pairings it works with—it handles all that cross-referencing for you. If you're narrowing down the options by a single characteristic, you've got several angles. Need something strong? You can use `get_beers_by_abv` to filter the whole list right down to the ABV range you want, whether it’s a low-alcohol session drinker or a high-proof beast. Sometimes you know what flavor profile you like, but not the name. The agent lets you focus on hops; using `get_beers_by_hops`, you'll only see beers featuring specific hop varieties, like Citra or Mosaic. Or maybe bitterness is your thing; use `get_beers_by_ibu` to separate everything mild from super-bitter bombs instantly. If you know the style—say, you're craving a Stout or an IPA—you can run that through `get_beers_by_style`. It filters out everything else. You also gotta consider what you’re eating with it; ask for pairings, and `get_beers_by_food` pulls matching brews based on food like cheese, dessert, or spicy dishes. Sometimes, you just don't know what you want to drink. No big deal. Use `get_random_beer`, and the server spits out a selection of random brews for you to check out—it’s great for discovery. And when you find one that looks promising, use its specific ID with `get_beer_by_id`. That tool gives you the deep dive: it pulls all the full specs on that single beer, including ingredient lists, brewing tips, and more pairing suggestions. You've got everything here—from a simple random pull to filtering down thousands of options using combination searches. You just tell your agent what you need, and it gets the right data back. ## Tools ### get_all_beers Search the entire catalog using a combination of filters like name, ABV limits, IBU range, malts, and food pairings. ### get_beer_by_id Retrieves full details—ingredients, brewing tips, and pairing suggestions—for one specific beer ID. ### get_beers_by_abv Filters the catalog to find beers within a specified alcohol by volume range (e.g., low ABV or high ABV). ### get_beers_by_food Finds and lists matching brews based on common food pairings like cheese, dessert, or spicy dishes. ### get_beers_by_hops Narrows the search to only include beers that feature specific hop varieties (like Citra or Mosaic). ### get_beers_by_ibu Filters results based on bitterness units, letting you find everything from mild to very bitter brews. ### get_beers_by_style Searches the catalog by specific beer style names, such as IPA, Stout, or Lager. ### get_random_beer Pulls a random selection of beers from the entire catalog for discovery purposes. ## Prompt Examples **Prompt:** ``` Give me a random beer suggestion. ``` **Response:** ``` Punk IPA (5.4% ABV, 35 IBU) — A post-modern classic. Juicy, tropical and citrusy with Cascade, Amarillo and Centennial hops. Pairs well with spicy Indian food. ``` **Prompt:** ``` Find me beers that pair well with cheese. ``` **Response:** ``` Found 15 beers that pair with cheese including: Dead Pony Club (light, session), 5AM Saint (amber ale), Hardcore IPA (strong IPA), Tokyo Rising (dark, intense). ``` **Prompt:** ``` Show me all BrewDog IPAs. ``` **Response:** ``` Found 20+ IPAs including: Punk IPA (5.4%, classic), Elvis Juice (6.5%, grapefruit), Hazy Jane (5%, New England style), Punk AF (0.5%, non-alcoholic), Lost Lager (4.5%). Each with full hop profiles and food pairings. ``` ## Capabilities ### Find beers for specific meals You ask the agent for a pairing (e.g., 'What beer goes with beef?'), and it runs tools to return matching brews. ### Filter by alcohol strength The client narrows down options using ABV ranges, allowing you to find anything from low-alcohol session beers to high-proof stouts. ### Search by flavor profile (hops) You can limit the search results to only feature specific hop types like 'Citra' or 'Mosaic'. ### Filter by bitterness level The agent uses IBU ranges to separate mild, balanced, and super-bitter beers instantly. ### Get a random beer suggestion You ask for something new, and the server pulls one or more random brews from the catalog for you to check out. ## Use Cases ### Menu Night Prep A restaurant manager needs a pairing for their new spicy taco platter. Instead of checking three different databases, they ask the agent: 'Find beers that pair with spicy food.' The agent runs `get_beers_by_food` and immediately returns 10 options suitable for the menu. ### Inventory Audit A brewery developer needs to know if they have any super-strong stouts. They ask: 'Show me all beers over 8% ABV that are also in the Stout style.' The agent combines `get_beers_by_abv` and `get_beers_by_style`, giving an accurate, filtered list. ### Researching Hops A craft beer writer needs to write about the versatility of Mosaic hops. They ask: 'Find all beers that use Mosaic.' The agent runs `get_beers_by_hops`, providing a list and linking to detailed ingredient profiles via `get_beer_by_id`. ### The Quick Recommendation A user just finished dinner and wants a suggestion. They ask: 'Give me a beer.' The agent runs `get_random_beer`, giving them an instant, fun discovery without needing any filters or input. ## Benefits - Stop guessing what pairs well. Use `get_beers_by_food` to instantly see 15+ beers that match a specific dish like 'cheese' or 'pork', eliminating menu guesswork. - Filter out the bad stuff. Instead of sifting through hundreds, use `get_beers_by_abv` to immediately narrow results to only those session beers under 4% ABV. - Drill down into specifics. If you know it's a Citra hop beer, run `get_beers_by_hops`. This gives you precision filtering that generic searches miss. - Handle complex queries in one shot. The `get_all_beers` tool lets your agent combine filters—for example, finding an 'IPA style' *and* with a 'Citra hop' *and* above 5% ABV. - Never get bored looking at beer data again. Use `get_random_beer` when you need quick, fun suggestions without having to define parameters. ## How It Works The bottom line is, you use your natural language prompt, and the server does all the complex filtering work in the background. 1. Subscribe to the PunkAPI server. No API key is needed—you're good to go. 2. Tell your AI client what you need (e.g., 'Find a beer for chicken that is low ABV'). 3. The agent runs multiple tools (`get_beers_by_food`, then `get_beers_by_abv`) and spits out the exact matching beers. ## Frequently Asked Questions **How do I use get_beers_by_abv? Should I combine it with other filters?** You can absolutely combine them. For example, you can ask for 'a low ABV IPA.' The agent will run `get_beers_by_style` (IPA) and then filter those results using `get_beers_by_abv` to meet both criteria. **What is the easiest way to find a beer for cheese?** Just call `get_beers_by_food('cheese')`. This tool specifically targets common pairings and returns all matching beers with their suggestions, making it fast and simple. **Can I use get_all_beers if I don't know the name?** Yes. `get_all_beers` is powerful because you can filter by multiple parameters—like a specific malt type *and* an ABV range—even if you don't have a beer name. **Do I need to use get_random_beer if I just want suggestions?** No, but it depends on the vibe. If you want quick discovery and don't care about criteria, `get_random_beer` is perfect. If you have constraints (like 'must be IPA'), stick to targeted filters. **How do I get full ingredient details for one beer using get_beer_by_id?** It returns a complete profile, including malts, hops, yeast, and brewing tips. This is better than searching generally because it focuses specifically on the single item's entire technical data sheet. **When should I use pagination parameters with get_all_beers?** You must use the page and per_page arguments when results exceed a few dozen. This prevents connection timeouts and allows you to pull massive catalog data in manageable, reliable chunks. **Can I combine get_beers_by_hops with other filters, like finding a specific style?** Yes. You can use the hop variety filter as one layer and feed that output into another tool (like `get_beers_by_style`) for refinement. Layered filtering gives you much more precise results. **What is the difference between low IBU and medium IBU when using get_beers_by_ibu?** Low IBU (<20) means a mild, subtle flavor profile, while Medium IBU (20-40) gives a balanced bitterness. These specific ranges help you nail down the exact level of bitterness you want. **Do I need an API key?** No! PunkAPI is completely free and open. No authentication required. Just subscribe and start searching beers. **What does ABV and IBU mean?** ABV (Alcohol By Volume) measures alcohol content percentage. IBU (International Bitterness Units) measures bitterness: 60 = very bitter.