使用说明

blinkit mcp

包装的MCP（模型上下文协议）服务器 Blinkkit.com --印度的快速商业杂货配送平台——使人工智能助手能够搜索产品、管理购物车和下订单。

Blinkit没有公共API。此服务器使用混合方法：在可能的情况下直接进行HTTP调用，并将Playwright浏览器自动化作为回退。Playwright在进程内运行，由BrowserManager类管理。

特性

认证 --基于OTP的电话登录，具有持久会话存储
产品搜索 --按关键字搜索、浏览类别、查看产品详细信息
购物车管理 --添加、更新、删除项目；查看购物车总计
结账和付款 --完整的结账流程，包括地址选择和UPI支付
订单追踪 --查看订单历史记录并实时跟踪当前交付情况
支出保障 --可配置的警告阈值和硬支出限制
位置感知 --自动基于IP的地理定位，手动覆盖（Blinkit库存是超本地的）

先决条件

Node.js v18或更高版本
pnpm 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可能会在服务器端使其无效。

许可证

麻省理工学院