# Open Brewery DB MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that provides access to the [Open Brewery DB](https://www.openbrewerydb.org/) 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:
```bash
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)
```bash
npx open-brewery-db-mcp
```
### Or clone and run locally
```bash
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:
```bash
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`
```json
{
"mcpServers": {
"open-brewery-db": {
"command": "npx",
"args": ["@jimbuck/open-brewery-db-mcp"]
}
}
}
```
Or, if installed locally or cloned:
```json
{
"mcpServers": {
"open-brewery-db": {
"command": "node",
"args": ["/path/to/open-brewery-db-mcp/dist/index.js"]
}
}
}
```
## About Open Brewery DB
[Open Brewery DB](https://www.openbrewerydb.org/) 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):
```bash
npm run dev
```
This command starts the server with the [MCP Inspector](https://github.com/modelcontextprotocol/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):
```bash
npm run watch
```
## API Examples
### Search for breweries in Portland
```json
{
"name": "search_breweries",
"arguments": {
"by_city": "Portland",
"by_state": "Oregon",
"per_page": 10
}
}
```
### Get a specific brewery
```json
{
"name": "get_brewery_by_id",
"arguments": {
"id": "11590"
}
}
```
### Get 3 random breweries
```json
{
"name": "get_random_brewery",
"arguments": {
"size": 3
}
}
```
## Data Schema
Each brewery object includes the following information:
```typescript
{
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](https://github.com/openbrewerydb/openbrewerydb) to suggest changes, add new breweries, or help maintain the dataset.
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Acknowledgments
- [Open Brewery DB](https://www.openbrewerydb.org/) for providing the excellent brewery API
- [Model Context Protocol](https://modelcontextprotocol.io) 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](https://www.openbrewerydb.org/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.
