Blinkit MCP

blinkit mcp


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

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

特性

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

先决条件

• v18或更高版本
• v8或更高版本
• Blinkit帐户（OTP登录的印度电话号码）

安装

1. 克隆存储库：

   git clone https://github.com/AmanVarshney01/blinkit-mcp.git
   cd blinkit-mcp

1. 安装依赖项：

   pnpm install

1. 使用Firefox安装Playwright：

   npx playwright install firefox

1. 创建配置目录：

   mkdir -p ~/.blinkit-mcp

1. （可选）使用默认值创建配置文件：

   {
     "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.环境变量覆盖基于文件的配置。

配置选项

环境变量

可用工具

身份验证（4个工具）

位置（3个工具）

浏览和搜索（4个工具）

购物车（5个工具）

订单和付款（6个工具）

总计：22个工具

建筑

混合HTTP+剧作家

Blinkit不公开公共API。此服务器采用双管齐下的方法：

1. 直接HTTP --对于经过逆向工程的端点（搜索、产品详细信息、类别、购物车操作）。这些既快速又轻便。
2. 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可能会在服务器端使其无效。

许可证

麻省理工学院