jimbuck/open-brewery-db-mcp

Open Brewery DB MCP Server

A Model Context Protocol (MCP) server that provides access to the Open Brewery DB API. This server enables AI assistants and other MCP clients to search for breweries, get detailed brewery information, and explore brewery data from around the world.

Installation

From npm (Recommended)

Install the package globally or as a dependency:

npm install -g @jimbuck/open-brewery-db-mcp
# or for local usage
npm install @jimbuck/open-brewery-db-mcp

Quick Start

Run with npx (no clone required)

npx open-brewery-db-mcp

Or clone and run locally

git clone https://github.com/your-username/open-brewery-db-mcp.git
cd open-brewery-db-mcp
npm install
npm run dev

This will start the server with the MCP Inspector - a web-based interface for testing and exploring all the brewery tools interactively!

As an MCP Server (for MCP clients)

The server communicates via stdio and follows the MCP protocol. To use it with an MCP client:

npm start
# or
node dist/index.js

MCP Client Configuration Example

To connect this server to an MCP client like Claude Desktop, add the following configuration:

macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "open-brewery-db": {
      "command": "npx",
      "args": ["@jimbuck/open-brewery-db-mcp"]
    }
  }
}

Or, if installed locally or cloned:

{
  "mcpServers": {
    "open-brewery-db": {
      "command": "node",
      "args": ["/path/to/open-brewery-db-mcp/dist/index.js"]
    }
  }
}

About Open Brewery DB

Open Brewery DB is a free and open-source API that provides comprehensive information about breweries worldwide. The database includes:

• 40,000+ breweries from around the globe
• Detailed brewery information including names, types, locations, and contact details
• Regular updates from community contributions
• No authentication required for basic usage

Brewery Types

The API categorizes breweries into several types:

• micro - Most craft breweries. For example, Samuel Adams is still considered a micro brewery
• nano - An extremely small brewery which typically only distributes locally
• regional - A regional location of an expanded brewery. Ex. Sierra Nevada Asheville
• brewpub - A beer-focused restaurant or restaurant/bar with a brewery on-premise
• large - (DEPRECATED) A very large brewery. Likely not for visitors. Ex. Miller-Coors
• planning - A brewery in planning or not yet opened to the public
• bar - (DEPRECATED) A bar. No brewery equipment on premise
• contract - A brewery that uses another brewery's equipment
• proprietor - Similar to contract brewing but refers to a brewery incubator
• closed - A location which has been closed

Features

This MCP server provides the following tools:

🔍 search_breweries

Search for breweries with flexible filtering options:

• by name - Search by brewery name
• by city - Filter by city name
• by state - Filter by state (full name or abbreviation)
• by type - Filter by brewery type (see types above)
• pagination - Control results with page and per_page parameters

🏭 get_brewery_by_id

Get detailed information about a specific brewery using its unique ID.

🎲 get_random_brewery

Discover new breweries by getting random brewery information. You can specify how many random breweries to retrieve (1-10).

📋 list_brewery_types

Get a complete list of all available brewery types with descriptions.

Usage

Development

For development with the MCP Inspector (recommended):

npm run dev

This command starts the server with the MCP Inspector, which provides:

• 🔍 Interactive testing of all MCP tools
• 📊 Real-time debugging of server responses
• 🎯 Visual tool exploration with a web-based interface
• 🚀 Instant feedback without needing to configure a full MCP client

The inspector will automatically open in your browser, allowing you to test brewery searches, explore random breweries, and validate all functionality in real-time.

To watch for changes and rebuild (production mode):

npm run watch

API Examples

Search for breweries in Portland

{
  "name": "search_breweries",
  "arguments": {
    "by_city": "Portland",
    "by_state": "Oregon",
    "per_page": 10
  }
}

Get a specific brewery

{
  "name": "get_brewery_by_id",
  "arguments": {
    "id": "11590"
  }
}

Get 3 random breweries

{
  "name": "get_random_brewery",
  "arguments": {
    "size": 3
  }
}

Data Schema

Each brewery object includes the following information:

{
  id: string;                    // Unique identifier
  name: string;                  // Brewery name
  brewery_type: BreweryType;     // Type of brewery
  address_1?: string;            // Street address
  address_2?: string;            // Additional address info
  address_3?: string;            // Additional address info
  city?: string;                 // City name
  state_province?: string;       // State or province
  postal_code?: string;          // Postal/ZIP code
  country?: string;              // Country
  longitude?: string;            // GPS longitude
  latitude?: string;             // GPS latitude
  phone?: string;                // Phone number
  website_url?: string;          // Website URL
  state?: string;                // US state code
  street?: string;               // Street address (alternative)
}

Rate Limiting

Open Brewery DB has reasonable rate limits:

• No authentication required for basic usage
• Please be respectful with API calls
• For high-volume usage, consider caching responses

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests: npm test
5. Commit your changes (git commit -m 'feat: Add some amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Brewery Data Contributions

Want to help improve the brewery data itself?
Contributions to the brewery listings and data are welcome! Check out the Open Brewery DB GitHub repository to suggest changes, add new breweries, or help maintain the dataset.

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Open Brewery DB for providing the excellent brewery API
• Model Context Protocol for the protocol specification
• All contributors to the brewery data

Support

If you encounter any issues or have questions:

1. Check the Open Brewery DB documentation
2. Open an issue in this repository
3. Check existing issues for similar problems

Note: This is an unofficial MCP server for Open Brewery DB. It is not affiliated with or endorsed by Open Brewery DB.