blinkit mcp
包装的MCP（模型上下文协议）服务器 Blinkkit.com --印度的快速商业杂货配送平台——使人工智能助手能够搜索产品、管理购物车和下订单。
Blinkit没有公共API。此服务器使用混合方法：在可能的情况下直接进行HTTP调用，并将Playwright浏览器自动化作为回退。Playwright在进程内运行，由BrowserManager类管理。
特性
- 认证 --基于OTP的电话登录，具有持久会话存储
- 产品搜索 --按关键字搜索、浏览类别、查看产品详细信息
- 购物车管理 --添加、更新、删除项目；查看购物车总计
- 结账和付款 --完整的结账流程，包括地址选择和UPI支付
- 订单追踪 --查看订单历史记录并实时跟踪当前交付情况
- 支出保障 --可配置的警告阈值和硬支出限制
- 位置感知 --自动基于IP的地理定位，手动覆盖（Blinkit库存是超本地的）
先决条件
- v18或更高版本
- v8或更高版本
- Blinkit帐户（OTP登录的印度电话号码）
安装
- 克隆存储库：
git clone https://github.com/AmanVarshney01/blinkit-mcp.git
cd blinkit-mcp- 安装依赖项：
pnpm install- 使用Firefox安装Playwright：
npx playwright install firefox- 创建配置目录：
mkdir -p ~/.blinkit-mcp- （可选）使用默认值创建配置文件：
{
"default_lat": 28.6139,
"default_lon": 77.2090,
"warn_threshold": 500,
"max_order_amount": 2000,
"headless": true
}将此保存到 ~/.blinkit-mcp/config.json。请参阅 配置 所有可用选项的部分。
MCP客户端配置
克劳德桌面版
将以下内容添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"blinkit": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/blinkit-mcp/src/index.ts"]
}
}
}克劳德代码
运行以下命令：
claude mcp add blinkit -- npx tsx /absolute/path/to/blinkit-mcp/src/index.ts通用MCP客户端
使用以下命令使用stdio传输：
npx tsx /absolute/path/to/blinkit-mcp/src/index.ts替换 /absolute/path/to/blinkit-mcp 使用克隆存储库的实际路径。
配置
配置从加载 ~/.blinkit-mcp/config.json.环境变量覆盖基于文件的配置。
配置选项
| 选项 | 类型 | 默认值 | 描述 |
|---|---|---|---|
default_lat | number | -- | 默认交货纬度（-90到90）。如果未设置，则回退到IP地理位置。 |
default_lon | number | -- | 默认交货经度（-180到180）。如果未设置，则回退到IP地理位置。 |
warn_threshold | number | 500 | 返回支出警告的购物车价值（INR）。 |
max_order_amount | number | 2000 | 硬限制（印度卢比）。如果购物车超过此金额，结账将被阻止。 |
headless | boolean | true | 在无头模式下运行Playwright浏览器。设置为 false 查看浏览器窗口。 |
debug | boolean | false | 启用调试日志记录。还强制使用头部模式并应用 slow_mo. |
slow_mo | number | 0 | 毫秒来减缓剧作家的每一个动作。可用于调试。默认值为500 debug 是 true. |
环境变量
| 变量 | 覆盖 |
|---|---|
BLINKIT_DEFAULT_LAT | default_lat |
BLINKIT_DEFAULT_LON | default_lon |
BLINKIT_WARN_THRESHOLD | warn_threshold |
BLINKIT_MAX_ORDER_AMOUNT | max_order_amount |
BLINKIT_HEADLESS | headless （设置为 "false" 禁用） |
BLINKIT_DEBUG | debug （设置为 "true" 启用） |
BLINKIT_SLOW_MO | slow_mo |
可用工具
身份验证（4个工具）
| 工具 | 说明 |
|---|---|
check_login_status | 检查当前会话是否已使用Blinkit进行身份验证 |
login | 使用电话号码启动OTP登录。发送短信OTP。 |
enter_otp | 提交通过短信收到的4位OTP以完成登录 |
logout | 注销并清除已保存的会话和身份验证令牌 |
位置（3个工具）
| 工具 | 说明 |
|---|---|
set_location | 通过搜索地址或地区名称设置交货位置 |
get_saved_addresses | 列出用户保存的送货地址（需要登录） |
select_address | 按索引选择一个保存的地址，以便在结账时送货 |
浏览和搜索（4个工具）
| 工具 | 说明 |
|---|---|
search_products | 按关键字搜索产品。返回名称、价格和ID。 |
get_product_details | 按ID获取产品的完整详细信息（价格、描述、品牌、营养、图片） |
browse_categories | 列出带有ID的顶级产品类别 |
browse_category | 获取特定类别或子类别中的产品 |
购物车（5个工具）
| 工具 | 说明 |
|---|---|
get_cart | 查看当前购物车内容、商品数量和总数（需要登录） |
add_to_cart | 按产品ID和可选数量将产品添加到购物车（需要登录） |
update_cart_item | 更改购物车商品的数量。设置为0以删除。（需要登录） |
remove_from_cart | 从购物车中删除特定数量的产品（需要登录） |
clear_cart | 清空整个购物车（需要登录） |
订单和付款（6个工具）
| 工具 | 说明 |
|---|---|
checkout | 从购物车进行结账。返回下一步提示(select_address 或 payment). |
get_order_history | 查看带有ID、日期、总计和状态的过去订单（需要登录） |
track_order | 获取订单的实时跟踪状态。默认为最新订单。（需要登录） |
get_upi_ids | 结账后从付款页面获取可用的UPI ID |
select_upi_id | 选择或输入用于支付的UPI VPA（例如。， user@ybl) |
pay_now | 通过确认付款完成交易 |
总计：22个工具
建筑
混合HTTP+剧作家
Blinkit不公开公共API。此服务器采用双管齐下的方法：
- 直接HTTP --对于经过逆向工程的端点（搜索、产品详细信息、类别、购物车操作）。这些既快速又轻便。
- Playwright浏览器自动化 --用于身份验证（OTP流）、结账、支付和任何不能直接调用的端点。默认情况下，在无头模式下使用Firefox。
每个工具都可以有HTTP或Playwright实现。该架构的设计使单个工具可以在发现端点时从Playwright迁移到直接HTTP。
进行中剧作家
浏览器自动化在进程内运行。这 BrowserManager 班级(src/core/browser-manager.ts)直接管理Playwright Browser、BrowseContext和Page实例。流量模块 src/playwright/ 将浏览器自动化逻辑作为普通异步函数包含在内。服务直接调用这些函数——没有子流程，没有IPC，没有序列化开销。
层次图
MCP Client (Claude, etc.)
|
stdio transport
|
MCP Server (Node.js)
|
+----+----+
| |
Tools Tools
| |
Services Services
| |
+----+----+
| |
HTTP Client Browser Manager
| |
Blinkit API Playwright Flow Modules
|
Firefox Browser层：
- MCP工具层 (
src/tools/)--带有输入模式和处理程序的MCP工具定义。委托给服务的薄包装。 - 服务层 (
src/services/)——商业逻辑。HTTP优先，Playwright回退。（AuthService、ProductService、CartService、OrderService、PaymentService、LocationService、SpendingGuard）。 - 核心层 (
src/core/)--基础架构组件（BrowserManager、BlinkitHttpClient、SessionManager、RateLimiter、Logger）。 - 剧作家流程模块 (
src/playwright/)--在Playwright页面上运行并返回键入结果的浏览器自动化功能。
会话保持
身份验证令牌和浏览器存储状态保存到 ~/.blinkit-mcp/ 以便会话在服务器重启后仍然存在。服务器在启动时尝试重用现有会话，并且仅在会话过期时触发重新身份验证。
用法示例
与AI助手的典型对话流程：
User: Order some groceries from Blinkit
1. [check_login_status] --> Not logged in
2. [login] phone_number: "9876543210" --> OTP sent
User: The OTP is 1234
3. [enter_otp] otp: "1234" --> Logged in successfully
4. [set_location] location_name: "Koramangala, Bangalore" --> Location set
User: Find me some milk
5. [search_products] query: "milk" --> Returns list of milk products with IDs and prices
User: Add the Amul Taaza 500ml to my cart
6. [add_to_cart] product_id: "12345", quantity: 2 --> Added to cart
User: What's in my cart?
7. [get_cart] --> Shows cart with items, quantities, and total
User: Looks good, let's checkout
8. [checkout] --> Returns next_step: "select_address"
9. [get_saved_addresses] --> Lists saved addresses
10. [select_address] address_index: 0 --> Address selected
11. [get_upi_ids] --> Lists available UPI IDs
12. [select_upi_id] upi_id: "user@ybl" --> UPI selected
User: Yes, go ahead and pay
13. [pay_now] --> Payment initiated, approve on your UPI app
User: Is my order on the way?
14. [track_order] --> Order confirmed, estimated delivery in 10 minutes故障排除
“商店不可用”或搜索结果为空
Blinkit库存是超本地化的。每家黑暗的商店都服务于一个小的地理区域。如果您得到空结果或“存储不可用”错误：
- 使用验证您的位置是否设置为Blinkit可用区域
set_location. - 请尝试其他地址。并非所有区域都有Blinkit覆盖。
- 有些产品只在某些黑暗的商店有库存。
未收到OTP或登录超时
- 确保电话号码是有效的10位印度手机号码（以6-9开头）。
- 请至少等待30秒，然后重试。Blinkit可能会限制OTP请求的速率。
- 编剧操作有60秒的超时时间。如果登录时间较长，操作将超时，需要重试该命令。
Playwright浏览器无法启动
- 确认Node.js v18+已安装并可在您的
PATH. - 确认Playwright已安装Firefox：运行
npx playwright install firefox. - 检查一下
tsx可用（它作为开发依赖项安装）。 - 集
debug到true在您的配置中查看浏览器窗口并获取详细日志。
速率限制
服务器包括内置的速率限制（令牌桶有5个令牌，以2/sec的速度重新填充，请求之间的最小间隔为200ms）。如果您遇到Blinkit的速率限制：
- 放慢请求速度。避免快速使用工具。
- 如果收到重复错误，请等待几分钟后重试。
- 速率限制参数当前不可由用户配置。
超出支出限额
如果结账被阻止，购物车总数已超过您的 max_order_amount （默认值：2000印度卢比）。删除项目以降低总数，或增加配置中的限制。
会话已过期
如果工具在一段时间不活动后返回身份验证错误，则您的Blinkit会话可能已过期。跑 check_login_status 然后 login 如果需要，再次。服务器将会话保存到磁盘，但Blinkit可能会在服务器端使其无效。
许可证
麻省理工学院