内容
# Brewfather MCP 服务器
一款与 Brewfather API 集成的模型上下文协议（MCP）服务器，提供酿造库存管理和配方分析功能。该服务器允许像 Claude 这样的 MCP 客户端与您的 Brewfather 酿造数据进行交互。
## 功能特点
- **库存管理**：列出和管理可发酵物质、啤酒花、酵母和其他酿造用品
- **配方分析**：访问包括原料和工艺细节在内的详细配方信息
- **批次跟踪**：监控酿造批次，更新测量值并跟踪进度
- **酿造洞察**：获取酿造工艺指导和传感器读数
## 前置条件
- Python 3.13 或更高版本
- 具有 API 访问权限的 Brewfather 账户
- Brewfather API 凭证（用户 ID 和 API 密钥）
## 获取您的 Brewfather API 凭证
1. 登录您的 Brewfather 账户
2. 导航到 设置 → API
3. 生成或复制您的 API 用户 ID 和 API 密钥
4. 安全保存这些凭证 - 您将需要它们进行配置
## 安装
### 选项 1：使用 uvx 直接安装（推荐）
使用 `uvx` 从 GitHub 仓库直接使用此 MCP 服务器的最简单方法：
```bash
# 将您的凭证设置为环境变量
export BREWFATHER_API_USER_ID="您的 API 用户 ID"
export BREWFATHER_API_KEY="您的 API 密钥"
# 运行服务器
uvx --from git+https://github.com/mindsocket/brewfather-mcp.git brewfather-mcp
```
用于调试：
```bash
uvx --from git+https://github.com/mindsocket/brewfather-mcp.git brewfather-mcp --debug
```
### 选项 2：本地开发安装
1. 克隆此仓库
2. 安装依赖项：
```bash
uv sync
```
## 配置
### Claude Desktop 配置
#### 选项 1：使用 uvx（推荐）
要通过 uvx 将此服务器与 Claude Desktop 一起使用，请在 Claude Desktop 配置文件中添加以下内容：
**配置文件位置：**
- macOS：`~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows：`%APPDATA%\\Claude\\claude_desktop_config.json`
**配置：**
```json
{
"mcpServers": {
"brewfather": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/mindsocket/brewfather-mcp.git",
"brewfather-mcp"
],
"env": {
"BREWFATHER_API_USER_ID": "您的 API 用户 ID",
"BREWFATHER_API_KEY": "您的 API 密钥"
}
}
}
}
```
#### 选项 2：使用本地安装
要从本地克隆使用此服务器与 Claude Desktop，请使用上述相同的配置文件位置，并使用此配置：
```json
{
"mcpServers": {
"brewfather": {
"command": "uv",
"args": [
"run",
"--with",
"mcp[cli]",
"mcp",
"run",
"/绝对路径/到/brewfather-mcp/src/main.py"
],
"cwd": "/绝对路径/到/brewfather-mcp",
"env": {
"BREWFATHER_API_USER_ID": "您的 API 用户 ID",
"BREWFATHER_API_KEY": "您的 API 密钥"
}
}
}
}
```
替换：
- `/绝对路径/到/brewfather-mcp` 为您的克隆仓库的绝对路径
- `您的 API 用户 ID` 为您的 Brewfather API 用户 ID
- `您的 API 密钥` 为您的 Brewfather API 密钥
您可能还需要提供 `uv` 命令的完整路径。
#### 其他 MCP 客户端
对于支持 stdio 传输的其他 MCP 客户端，请使用：
- **命令**：`uv run --with mcp[cli] mcp run src/main.py`
- **工作目录**：此仓库的路径
- **环境变量**：`BREWFATHER_API_USER_ID` 和 `BREWFATHER_API_KEY`
### 用于本地开发和测试
在本地开发或测试服务器时，可以选择通过 `.env` 文件提供凭证：
```bash
cp .env.example .env
# 使用您的 Brewfather API 凭证编辑 .env
```
## 可用工具
服务器提供以下 MCP 工具：
### 库存管理
- `list_fermentables` - 列出所有可发酵物质（麦芽、辅料、谷物）
- `get_fermentable_detail(identifier)` - 获取详细的可发酵物质信息
- `list_hops` - 列出所有啤酒花及其特性，如 alpha 酸含量
- `get_hop_detail(identifier)` - 获取详细的啤酒花信息
- `list_yeasts` - 列出所有酵母及其减弱和类型
- `get_yeast_detail(identifier)` - 获取详细的酵母信息
- `list_misc_items` - 列出杂项酿造用品
- `get_misc_detail(item_id)` - 获取详细的杂项物品信息
- `inventory_summary` - 获取综合库存概览
### 配方管理
- `list_recipes` - 列出所有配方
- `get_recipe_detail(recipe_id)` - 获取详细的配方信息
### 批次管理
- `list_batches` - 列出所有酿造批次
- `get_batch_detail(batch_id)` - 获取详细的批次信息
- `update_batch(batch_id, ...)` - 更新批次测量值和状态
- `get_batch_brewtracker(batch_id)` - 获取酿造工艺指导
- `get_batch_last_reading(batch_id)` - 获取最新的传感器读数
- `get_batch_readings_summary(batch_id)` - 获取传感器读数摘要
### 库存更新
- `update_fermentable_inventory(item_id, amount)` - 更新可发酵物质库存
- `update_hop_inventory(item_id, amount)` - 更新啤酒花库存
- `update_yeast_inventory(item_id, amount)` - 更新酵母库存
- `update_misc_inventory(item_id, amount)` - 更新杂项物品库存
## 开发
### 运行测试
```bash
uv run pytest
```
### 在本地测试服务器
[mcptools](https://github.com/f/mcptools) 可用于本地测试：
```bash
# 列出可用工具
mcpt tools uv run --with 'mcp[cli]' mcp run src/main.py
# 调用特定工具
mcpt call list_inventory_categories uv run --with 'mcp[cli]' mcp run src/main.py
```
### HTTP/SSE 服务器（用于云部署）
```bash
PYTHONPATH=src uv run python src/http_runner.py --port 8000
```
## 故障排除
### 常见问题
1. **导入错误**：确保您已运行 `uv sync` 以安装所有依赖项
2. **API 身份验证错误**：
- 对于 MCP 客户端：检查您的凭证是否在客户端配置中正确设置
- 对于本地开发：确保您的 `.env` 文件存在且凭证有效
- 验证您的 Brewfather API 凭证是否正确且具有必要的权限
3. **连接超时**：检查您的互联网连接和 Brewfather API 状态
4. **Claude Desktop 中的路径问题**：确保您在配置文件中使用绝对路径
### 调试模式
启用调试模式以将 API 响应保存到调试文件夹中进行故障排除：
```bash
BREWFATHER_MCP_DEBUG=1 mcpt call get_batch_detail --params '{"batch_id": "您的批次 ID"}' uv run --with 'mcp[cli]' mcp run src/main.py
```
