Skip to main content
Glama

kfc-cn-mcp

肯德基中国(order.kfc.com.cn)点餐 MCP 服务器,为 Hermes Agent 适配,同时兼容任何支持 stdio 的 MCP 客户端(Claude Desktop、Cursor、Cherry Studio 等)。

它把肯德基中国 H5 点餐的真实接口封装成一组工具:找门店 → 看菜单 → 加购物车 → 结算预览 → 提交订单。不依赖浏览器自动化,直接走官方 H5 的 JSON 接口(含 KBS 签名与字段加密),因此速度快、资源占用低,价格与库存都是真实的。

本项目参考了 markswendsen-code/mcp-kfc 的工具形态(search_menu / add_to_cart / view_cart / checkout …),但美国 KFC 的实现是 Playwright 点击网页 + 估算价格;中国版是重写的 HTTP 客户端,能真正在肯德基中国下单。


1. 能力与边界

已实现

工具

作用

find_stores

按关键词 + 城市国标码,或经纬度找门店,返回 storeCode

select_store

选定门店并加载该店实时菜单(走 validStore → changeStoreOrAddress → cart/create → menu/list)

get_menu

查看分类/某个分类下的餐品(linkId、价格、是否套餐)

search_menu

按中文名/描述搜索餐品

get_item

商品详情 + 套餐可选内容(comboRounds)+ 规格

cart_add

加购;套餐可不传 selections 自动按最少份数选默认项

cart_set_quantity

修改某行数量(0 = 删除)

cart_remove

删除某行

cart_clear

清空购物车

cart_view

查看购物车与合计

preview_order

服务端结算预校验,返回金额、门店、是否需登录、previewToken

place_order

真实下单(生成未支付订单);必须 confirm=true + previewToken + 手机号

order_status

查询订单状态(实验性,可能需要登录态)

session_status

查看当前门店/购物车/会话状态,便于排障

明确不做

  • 不处理支付:place_order 成功后订单处于“未支付”,用餐人需在 15 分钟内到肯德基 App / H5「我的订单」完成微信/支付宝支付;超时自动取消。本 MCP 不接触支付密码、验证码、银行卡。

  • 不保存账号密码:默认免登录点餐(H5 的「免登录点餐」能力)。会员价、优惠券、大神卡、积分等需要登录的权益暂未接入。

  • 不绕过风控:若肯德基触发人机验证(geetest),工具会返回提示,需要用餐人在 App/H5 内完成。

  • 不做预约时段:默认“尽快取餐”。H5 的「预约」选时间尚未封装(接口已具备,后续可加)。


Related MCP server: mcp-telepizza

2. 环境要求

  • Node.js ≥ 18.17(建议 20/22/24)

  • 能直连 order.kfc.com.cn、store.kfc.com.cn(如公司网络有代理,请给 Hermes 进程配置 HTTPS_PROXY)

  • Hermes Agent(标准安装已含 MCP 支持)


3. 安装与构建

git clone <this-repo> kfc-cn-mcp
cd kfc-cn-mcp
npm install
npm run build

构建产物是 dist/index.js,Hermes 直接用 node 启动它,不需要常驻服务。

自检(会真实访问肯德基接口,只读 + 加购/清空购物车,不会下单):

npm run smoke

成功时最后一行是 SMOKE OK。


4. 接入 Hermes

4.1 写入 ~/.hermes/config.yaml

把下面的片段合并进 mcp_servers(Windows 示例,路径改成你的实际路径):

mcp_servers:
  kfc_cn:
    command: "node"
    args:
      - "C:/Users/你的用户名/kfc-cn-mcp/dist/index.js"
    env:
      KFC_STATE_DIR: "C:/Users/你的用户名/.kfc-cn-mcp"
      # 默认城市:上海 310100;北京 110100;深圳 440300;广州 440100
      KFC_CITY_CODE: "310100"
      # 默认坐标(用于“附近门店”推荐,可改成你的常用位置)
      KFC_LATITUDE: "31.2304"
      KFC_LONGITUDE: "121.4737"
    timeout: 60
    connect_timeout: 20
    tools:
      include:
        - find_stores
        - select_store
        - get_menu
        - search_menu
        - get_item
        - cart_add
        - cart_set_quantity
        - cart_remove
        - cart_clear
        - cart_view
        - preview_order
        - place_order
        - order_status
        - session_status
      prompts: false
      resources: false

完整可复制版本见 hermes/config.snippet.yaml。

4.2 或者用 hermes mcp add

hermes mcp add kfc_cn --command node --args "C:\path\to\kfc-cn-mcp\dist\index.js"

然后编辑 ~/.hermes/config.yaml 补上 env 和 tools.include(hermes mcp add 不一定支持一次写入全部字段)。

4.3 验证

hermes mcp test kfc_cn

应能看到 14 个工具。然后在 Hermes 会话里:

/reload-mcp

问一句:「用 kfc_cn 的工具查一下上海淮海路附近的肯德基」。

Hermes 注册后的工具名形如:

mcp_kfc_cn_find_stores
mcp_kfc_cn_select_store
mcp_kfc_cn_search_menu
mcp_kfc_cn_cart_add
mcp_kfc_cn_preview_order
mcp_kfc_cn_place_order
...

4.4 收紧权限(推荐)

如果只想让 Hermes 查菜单、不想让它下单,把 place_order 从 tools.include 里删掉即可;购物车工具可以保留。

Hermes 支持 tools.exclude,也可以反过来只排除危险工具:

    tools:
      exclude: [place_order]

4.5 装配套 Skill(可选)

hermes/skills/kfc-cn-ordering/SKILL.md 是一份 Hermes Skill,教模型按正确顺序调用工具、什么时候必须停下来让用户确认。复制到 Hermes 技能目录:

# Windows
Copy-Item -Recurse hermes\skills\kfc-cn-ordering "$env:USERPROFILE\.hermes\skills\"

# macOS / Linux
mkdir -p ~/.hermes/skills
cp -r hermes/skills/kfc-cn-ordering ~/.hermes/skills/

之后在 Hermes 里输入 /kfc-cn-ordering 或直接说“帮我点肯德基”,它会按 Skill 的流程执行。


5. 使用示例

你:帮我看看上海淮海路附近有哪些肯德基。
AI:(find_stores keyword=淮海路 cityCode=310100)
    附近有「淮海路餐厅 SH1146」「淮海路新金钟餐厅 SH2103」…

你:选淮海路餐厅,看看有什么汉堡。
AI:(select_store storeCode=SH1146 → get_menu category=汉堡卷)
    培根鸡腿肉霸堡 ¥24.90、泰夯Q虾鸡腿肉霸堡 ¥24.90…

你:来一个培根鸡腿肉霸堡,再加一个特大号鸡腿桶。
AI:(cart_add → cart_view)
    购物车:培根鸡腿肉霸堡 ×1、S特大号鸡腿桶 ×1,合计 ¥64.80

你:可以,手机号 138****8000,堂食。
AI:(preview_order → place_order confirm=true phone=… previewToken=…)
    订单已提交:订单号 1793…,合计 ¥64.80。
    请在 15 分钟内到肯德基 App「我的订单」完成支付。

套餐选择

get_item 会返回:

{
  "comboRounds": [
    {
      "roundId": "1",
      "name": "小食",
      "minCount": 2,
      "maxCount": 2,
      "items": [{ "linkId": "100129945", "name": "特大号鸡腿1个", "maxCount": 2 }]
    }
  ]
}

加购时可以显式指定:

{
  "items": [
    {
      "linkId": "100129947",
      "quantity": 1,
      "selections": { "1": [{ "linkId": "100129945", "quantity": 2 }] }
    }
  ]
}

不传 selections 时,会按每轮 minCount 自动选第一个可选项(与 H5 默认行为一致)。


6. 环境变量

变量

默认值

说明

KFC_STATE_DIR

~/.kfc-cn-mcp

会话 cookie、sessionId、菜单缓存、购物车状态目录

KFC_CITY_CODE

310100

默认城市国标码(find_stores 未传 cityCode 时使用)

KFC_LATITUDE / KFC_LONGITUDE

31.2304 / 121.4737

默认坐标(上海人民广场),用于附近门店与切换门店时的距离计算

KFC_HTTP_TIMEOUT_MS

20000

单次接口超时

城市国标码示例:北京 110100、上海 310100、广州 440100、深圳 440300、杭州 330100、成都 510100、南京 320100、武汉 420100。


7. 状态与并发

  • 状态保存在 KFC_STATE_DIR/session.json(cookie + sessionId + 购物车)与 menu.json(菜单缓存,30 分钟有效)。

  • 每个 Hermes 会话会拉起一个 MCP 进程;同一时间只应有一个进程操作同一个 KFC_STATE_DIR,否则购物车会互相覆盖。多开时给每个进程设置不同的 KFC_STATE_DIR。

  • session.json 里有肯德基会话 cookie,属于敏感文件;不要提交到 Git(项目已 .gitignore)。


8. 故障排查

现象

原因/处理

无法连接肯德基接口 … ECONNRESET / ETIMEDOUT

网络或代理问题。给 Hermes 配 HTTPS_PROXY,或换网络。

初始化门店菜单失败:参数错误

接口/版本变化,或门店不支持自取。先 find_stores 换门店。

会话已过期

已自动重建会话并重试;若仍失败,重新 select_store。

商品校验失败,可能已售罄

菜单缓存过期,get_menu(refresh=true) 后重新加购。

触发人机验证

肯德基风控,需在 App/H5 人工完成,MCP 无法绕过。

hermes mcp test 失败

检查 node 是否在 PATH、args 是否是绝对路径、dist/index.js 是否已构建。

工具列表里没有 place_order

被 tools.include/exclude 过滤了。

下单成功但没看到支付入口

打开肯德基 App →「我的」→「订单」,或 order.kfc.com.cn 的订单页;未支付订单 15 分钟后取消。


9. 实现说明(给维护者)

详细接口笔记见 docs/API-NOTES.md。核心点:

  • H5 入口:https://order.kfc.com.cn/preorder-taro/menu

  • 预订单接口:https://order.kfc.com.cn/preorder-portal

  • 门店接口:https://order.kfc.com.cn/store-portal

  • 每个请求带 kbck / kbcts / kbsv 三个头;kbsv = md5(client_key \t client_sec \t 时间戳 \t 路径 \t\t 完整 JSON body)。

  • encodeList 里的字段(手机号、经纬度、门店坐标等)用 DES-CBC(key=iv=D963r1wp,PKCS7,Base64)加密。

  • cart/update 的 quantity 是增量而不是绝对值(已实测);删除用 cart/clearItem。

  • 这些常量来自公开 H5 bundle,官方改版后可能需要重新提取;代码里集中在 src/crypto.ts,便于更新。


10. 合规与免责

  • 仅供个人学习与自用。请遵守肯德基用户协议、门店规则与当地法律。

  • 请勿用于代下单、黄牛、批量刷单、爬取价格或其他商业用途。

  • 下单会产生真实订单(未支付也会占用门店产能),请确保用餐人确认后再调用 place_order。

  • 项目与肯德基(Yum China)无关联;接口可能随时变更,维护者不对下单失败、价格变动、订单取消等负责。

  • 参考项目:markswendsen-code/mcp-kfc(MIT)。


11. License

MIT

Available Tools

14 tools
cart_addAdd to cartA

Add dishes to the cart (套餐可传 selections;不传则按套餐最少份数自动选择). 加购;数量累加,套餐会自动选默认规格。

Inputs: items (required).

cart_clearClear cartB

Remove every dish from the cart. 清空购物车。

Inputs: no named parameters.

cart_removeRemove cart lineA

Remove one line from the cart by lineKey or linkId. 删除购物车中的一行。

Inputs: lineKey (required).

cart_set_quantitySet cart quantityA

Set the quantity of one cart line (0 removes it). 修改购物车某一行的数量,0 表示删除;lineKey 来自 cart_view。

Inputs: lineKey (required), quantity (required).

cart_viewView cartB
Read-only

Show cart lines, quantities and total. 查看购物车。

Inputs: no named parameters.

find_storesFind KFC China storesA
Read-only

Find KFC China restaurants by 门店关键词 + 城市国标码 (gbCityCode, e.g. 310100 = Shanghai) or by latitude/longitude. Returns storeCode you pass to select_store. 查询肯德基门店,返回 storeCode。

Inputs: limit, keyword, cityCode, latitude, +1 more.

get_itemGet item detailB
Read-only

Get dish detail plus combo rounds (套餐可选内容) and option groups. 查商品详情;套餐会返回 comboRounds(roundId、可选商品、最少/最多份数)。

Inputs: name, linkId.

get_menuGet menuA
Read-only

List the selected store menu: categories with item counts, or all items of one category. 查看菜单分类或某个分类下的餐品(linkId/价格/是否需要选规格)。

Inputs: limit, refresh, category, includeItems.

order_statusOrder statusB
Read-only

Check an order status by orderId (experimental; KFC may require the logged-in account). 查询订单状态,实验性接口。

Inputs: orderId (required).

place_orderPlace orderA

Submit the previewed order to KFC China. Requires confirm=true, the previewToken from preview_order and the diner phone. Creates a real unpaid order; payment must be completed by the diner in the KFC app/H5. 真实下单(会生成未支付订单),必须显式 confirm=true。

Inputs: phone (required), confirm (required), previewToken (required), remark, +2 more.

preview_orderPreview orderA
Read-only

Server-side price/stock validation before ordering (locks the current price) and returns a previewToken for place_order. 结算预校验,返回金额、门店、是否需登录和 previewToken(10 分钟内有效)。

Inputs: no named parameters.

search_menuSearch menuB
Read-only

Fuzzy-search dishes in the selected store menu by Chinese name/description. 按中文名/描述搜索餐品,返回 linkId、价格、是否需要选规格。

Inputs: query (required), limit.

select_storeSelect storeA

Bind the ordering session to one KFC China store by storeCode and load its live menu. 选定门店并加载菜单;之后所有购物车/下单都针对该门店。

Inputs: storeCode (required).

session_statusSession statusA
Read-only

Show current store, cart, preview and session age for troubleshooting. 查看当前会话/门店/购物车状态。

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 14 tools

    Disambiguation5/5

    Each tool targets a distinct step or resource in the ordering flow: store discovery (find_stores), session binding (select_store), menu browsing (get_menu/search_menu/get_item), cart mutation (add/set_quantity/remove/clear/view), and checkout (preview_order/place_order). The menu trio is related but clearly differentiated as list vs. fuzzy search vs. detail lookup, and the cart verb set is unambiguous.

    Naming Consistency3/5

    Two conventions coexist: verb_noun tools (find_stores, select_store, get_menu, search_menu, get_item, preview_order, place_order) and noun_verb/noun_noun tools (order_status, session_status, cart_add, cart_set_quantity, cart_remove, cart_clear, cart_view). The cart_ prefix group is internally readable, but the mixed verb/noun ordering across the set prevents a higher score.

    Tool Count5/5

    14 tools is well within the healthy range and every tool maps to a necessary stage of a food-ordering lifecycle. The five cart tools (add, set_quantity, remove, clear, view) each earn their place rather than being redundant wrappers.

    Completeness4/5

    The surface covers the full flow from store lookup through real order submission plus order status and session troubleshooting. Minor gaps exist: no order history/list, no order cancellation, and payment is intentionally delegated to the KFC app, which agents must work around.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Unofficial read-only MCP server for Telepizza.es that enables querying menu, prices, offers, stores, loyalty points, and order history using your own account. It cannot make purchases.
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables ordering from McDonald's through an interactive UI: selecting stores, browsing menus, managing a cart, applying coupons, placing orders, paying, and tracking orders.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables Egyptian-Arabic restaurant ordering over Streamable HTTP, exposing 11 tools for Arabic menu search, cart edits, VAT-quoted totals, confirmed order placement, order status/history, and weekday-based reordering with cross-session memory of orders and preferences.
      MIT