内容
# 🍇 Vivino MCP 服务器
**多年的葡萄酒评分，终于可以被你的 AI 读取。问它该喝什么。**
一个 MCP（模型上下文协议）服务器，将您的 Vivino 葡萄酒评分带入 Claude 和其他 AI 应用程序。访问个人葡萄酒数据，搜索 Vivino 目录，读取结构化的品尝资料，并将您的评分同步到 Obsidian，所有这些都来自一个聊天。
## 功能
- **获取个人评分** — 获取您的 Vivino 葡萄酒评分，支持筛选、分页和日期范围
- **葡萄酒详情** — 获取关于葡萄酒的综合信息（葡萄品种、地区、酒精度、食物搭配、社区评分）
- **品尝资料** — 获取结构化的感官分析（酸度、甜度、单宁、强度、泡沫度）和风味关键词
- **葡萄酒评论** — 访问社区和评论家的品尝笔记
- **搜索葡萄酒** — 按名称、酒庄、地区或葡萄品种搜索 Vivino 目录
- **Obsidian 同步** — 将您的评分导出为 markdown 笔记，并自动丰富（详情 + 品尝资料 + 食物搭配）
## 前置条件
- Node.js 18+ 和 npm
- 一个 Vivino 账户（vivino.com）
- 可选：Obsidian 保险库用于同步评分
- 可选：Exa API 密钥用于基于 Web 的葡萄酒丰富
## 安装
```bash
git clone https://github.com/yourusername/vivino-mcp-server.git
cd vivino-mcp-server
npm install
npm run build
```
## 设置
### 1. 获取您的 Vivino 会话 Cookie
1. 在浏览器中打开 [vivino.com](https://vivino.com) 并登录
2. 打开 Chrome 开发工具（F12 / Cmd+Option+I）
3. 进入 **应用程序** → **Cookie** → **vivino.com**
4. 查找 cookie(s) — 复制它们的名称和值（例如， `_session_id=abc123` ）
5. 保存到 `.env` 中，如： `VIVINO_SESSION_COOKIE=_session_id=abc123; other_cookie=val`
### 2. 获取您的 Vivino 用户 ID（可选）
如果您跳过此步骤，服务器将抓取您的用户名以解析您的用户 ID（较慢）。
1. 在 vivino.com 上，进入 **开发工具** → **网络** 标签
2. 刷新页面
3. 查找任何发送到 `/api/users/{number}/...` 的 XHR 请求
4. 复制该数字并保存到 `.env` 中，如： `VIVINO_USER_ID=<your_number>`
### 3. 设置 Vivino 用户名
将您的 Vivino 用户名添加到 `.env` 中：
```bash
VIVINO_USERNAME=your_username
```
### 4. 可选：Obsidian 同步路径
如果您想使用 Obsidian 同步功能，请设置：
```bash
OBSIDIAN_VAULT_PATH=/path/to/your/Obsidian Vault/Knowledge/Wine
```
### 5. 创建 `.env` 文件
复制 `.env.example` 并填写您的值：
```bash
cp .env.example .env
# 使用您的凭证编辑 .env
```
## 使用
### 使用 Claude 代码
添加到您的 Claude 代码 `.claude/launch.json` 中：
```json
{
"version": "0.0.1",
"configurations": [
{
"name": "vivino-mcp",
"runtimeExecutable": "node",
"runtimeArgs": ["/path/to/vivino-mcp-server/dist/index.js"],
"port": 0
}
]
}
```
然后在 Claude 代码中使用 `/start vivino-mcp` 启动 MCP 并访问工具。
### 独立使用 MCP 客户端
```bash
npm run dev
# 或
npm run start
```
服务器监听标准输入并输出到标准错误。
## API 参考
### vivino_get_user_ratings
获取您的个人葡萄酒评分。
**参数：**
- `page` （数字，默认：1）— 分页页码
- `per_page` （数字，默认：25，最大：100）— 每页结果数
- `min_rating` （数字，1.0–5.0）— 筛选：最低评分
- `max_rating` （数字，1.0–5.0）— 筛选：最高评分
- `since` （字符串，ISO 8601）— 筛选：新于此日期的评分
**示例：**
```
get my wine ratings since 2025-01-01 with min_rating 4.0
```
### vivino_get_wine_details
获取特定葡萄酒的综合信息。
**参数：**
- `wine_id` （数字，必填）— Vivino 葡萄酒 ID
**返回：**
- 葡萄品种、地区、国家、酒精度、风格描述
- 社区平均评分和总评分数
- 食物搭配建议
- Vivino URL
### vivino_get_wine_taste_profile
获取葡萄酒的结构化感官资料。
**参数：**
- `wine_id` （数字，必填）— Vivino 葡萄酒 ID
**返回：**
- 结构指标（酸度、甜度、单宁、强度、泡沫度）在 0–1 尺度上
- 风味组与主要关键词（例如，黑色水果、橡木、泥土、 floral）
### vivino_get_wine_reviews
获取社区和评论家的品尝笔记。
**参数：**
- `wine_id` （数字，必填）— Vivino 葡萄酒 ID
- `page` （数字，默认：1）
- `per_page` （数字，默认：10，最大：50）
### vivino_search_wines
搜索 Vivino 目录。
**参数：**
- `query` （字符串，必填）— 葡萄酒名称、酒庄、地区或葡萄品种
- `country_codes` （字符串数组）— 筛选：国家代码（例如，“fr”，“it”，“us”）
- `wine_type_ids` （数字数组）— 筛选：1=红酒，2=白酒，3=起泡酒，4=玫瑰酒，7=甜点酒，24=强化酒
- `min_rating` / `max_rating` （数字，1.0–5.0）— 按社区评分筛选
### vivino_sync_to_obsidian
将您的评分导出到 Obsidian。
**参数：**
- `full_sync` （布尔值，默认：false）— 从头开始获取所有评分（默认增量）
- `overwrite_existing` （布尔值，默认：false）— 覆盖现有笔记文件
- `max_wines` （数字，1–500）— 限制处理（适用于测试）
**要求：**
- 必须设置 `OBSIDIAN_VAULT_PATH` 环境变量
**输出：**
- 每种葡萄酒的单个 `.md` 文件，包含评分、品尝笔记、详情和品尝资料
- `Index.md`，包含按世界地区和国家排序的所有评分
- `.sync-state.json`，用于增量同步跟踪
## 测试
```bash
npm test # 运行测试一次
npm run test:watch # 监视模式
```
## 故障排除
### 无效会话 Cookie
**错误：** `CSRF token validation failed` 或 `Invalid session`
**解决方法：** 您的会话 Cookie 已过期。重复上述设置步骤以获取新的 Cookie。
### 速率限制
**错误：** `429 Too Many Requests`
**原因：** 请求太快。服务器自动实施速率限制（请求之间 700ms）和指数退避。
**解决方法：** 等待几分钟后重试。如果持续出现，请检查您是否没有运行多个实例。
### Obsidian 路径未找到
**错误：** `OBSIDIAN_VAULT_PATH 未设置` 或路径不存在
**解决方法：** 在 `.env` 中将 `OBSIDIAN_VAULT_PATH` 设置为 Obsidian 保险库的 Wine 知识库文件夹的完整路径。
### 需要用户名
**错误：** `Vivino 用户名未提供`
**解决方法：** 在 `.env` 中使用您的 Vivino 用户名设置 `VIVINO_USERNAME`。
## 许可证
MIT — 请参阅 [LICENSE](LICENSE) 获取详细信息。
## 贡献
欢迎贡献。请打开问题或拉取请求。
