MGC_MCP
This server provides Mega MGC Coffee store/menu lookup and stock (sold-out) checking tools via the app API.
refresh_mgc_stores: Fetch all Mega MGC Coffee app stores and save/update a local JSON cache.
list_mgc_stores_by_region: List cached stores filtered by region (city/district/neighborhood or free-form query); auto-refreshes cache if missing/expired.
find_mgc_stores: Find nearby stores by latitude/longitude or search by Korean district/city name.
search_mgc_menu: Search public Mega MGC Coffee menu pages by Korean or English menu text.
check_mgc_stock: Check stock for a menu item at a single store, by store code/name, or via general menu; returns available/sold_out/unknown.
check_mgc_stock_nationwide: Check stock across all or region-filtered stores nationwide, including notListed classification for stores not carrying the item.
check_mgc_stock_by_region: Check stock only for stores matching a specific region query, with configurable concurrency and result limits.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MGC_MCP check stock of vanilla latte at all Gangnam stores"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
메가MGC커피 앱 재고조회 MCP 재현 가이드
작성일: 2026-07-04 (KST)
대상 앱: 메가MGC커피 Android 앱 co.kr.waldlust.megacoffee
확인 버전: 2.0.7 / versionCode=85
기준 방식: ADB 연결 단말의 앱 화면 및 APK smali 분석, 앱 API 실호출
1. 목적
이 문서는 메가MGC커피 앱에서 사용하는 API를 바탕으로,
상품 검색, 매장 검색, 매장별 sold_out 재고 상태 조회를 재현하고 MCP 도구로 호출하는 절차를 정리합니다.
현재 MCP 서버는 다음 작업을 지원합니다.
메가MGC커피 매장 조회
앱 메뉴 검색
단일 매장 상품 재고 조회
전국 매장 대상 상품 재고 조회
지역 매장 대상 상품 재고 조회
전체 매장 리스트 캐싱 및 캐시 기반 지역 검색
Related MCP server: mcp-coffee
2. 핵심 엔드포인트
베이스 URL:
https://app.annhouse.co.kr/api/
APK 분석에서 확인된 추가 베이스 URL:
https://preview-app.mgcglobal.co.kr/api/https://devapp.annhouse.co.kr/api/
현재 구현에서 사용하는 핵심 엔드포인트:
메뉴 목록:
POST /api/menu/general/list추천 메뉴 목록:
POST /api/menu/rcmnd/list메뉴 검색:
POST /api/menu/search메뉴 옵션:
POST /api/menu/option매장 목록:
POST /api/store/list
재고 판정에 사용하는 필드:
상품 코드:
item_cd상품명:
item_nm가격:
price이미지:
img품절 여부:
sold_out매장 코드:
store_cd
3. 공통 요청 조건
실측 기준 최소 헤더:
content-type: application/jsonaccept: application/jsonuser-agent: okhttp/4.12.0
환경 변수로 API 베이스 URL과 User-Agent를 바꿀 수 있습니다.
MGC_APP_API_BASE_URLMGC_APP_USER_AGENT
실행 인자로도 같은 값을 지정할 수 있습니다.
--app-api-base-url--app-user-agent--stock-api-url
4. 재현 명령
A. 전체 메뉴 목록 조회
curl -sS 'https://app.annhouse.co.kr/api/menu/general/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'user-agent: okhttp/4.12.0' \
--data '{"store_cd":""}' \
| jq '.all.upper_ctg_list[0].ctg_list[0].item_list[0] | {item_cd,item_nm,price,sold_out,img}'기대 결과:
item_cd,item_nm존재sold_out값 확인 가능
B. 특정 매장 기준 메뉴 목록 조회
curl -sS 'https://app.annhouse.co.kr/api/menu/general/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'user-agent: okhttp/4.12.0' \
--data '{"store_cd":"001638"}' \
| jq '.. | objects | select(.item_cd? == "107350") | {item_cd,item_nm,price,sold_out}'기대 결과:
해당 매장에서 상품이 노출되면
item_cd: "107350"반환sold_out: true이면 품절sold_out: false이면 판매 가능결과가 없으면 해당 매장 메뉴에 노출되지 않은 상태
C. 매장 목록 조회
curl -sS 'https://app.annhouse.co.kr/api/store/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'user-agent: okhttp/4.12.0' \
--data '{
"use_location": false,
"latitude": "0",
"longitude": "0",
"keyword": "",
"amenities_cd_list": [],
"page": 1,
"page_size": 20,
"item_list": []
}' \
| jq '.store_list[0] | {store_cd,name,addr,status,latitude,longitude}'기대 결과:
store_cd,name,addr존재
D. 위치 기반 근처 매장 조회
curl -sS 'https://app.annhouse.co.kr/api/store/list' \
-H 'content-type: application/json' \
-H 'accept: application/json' \
-H 'user-agent: okhttp/4.12.0' \
--data '{
"use_location": true,
"latitude": "37.4979",
"longitude": "127.0276",
"keyword": "",
"amenities_cd_list": [],
"page": 1,
"page_size": 10,
"item_list": []
}' \
| jq '.store_list[] | {store_cd,name,addr}'기대 결과:
지정 좌표 주변 매장 목록 반환
E. 전국 매장별 상품 노출 및 품절 상태 재현
전국 조회는 다음 절차를 반복합니다.
POST /api/store/list를page증가 방식으로 호출해 전체 매장 수집전체 매장 리스트를
data/mgc-stores.json에 캐싱지역 조건이 있으면 캐시된 매장명/주소 기준으로 필터링
각
store_cd로POST /api/menu/general/list호출item_cd또는 상품명으로 메뉴 검색메뉴가 있으면
sold_out으로 판매 가능/품절 판정메뉴가 없으면
notListed로 분류
캐시 파일:
기본 경로: 패키지 내부
data/mgc-stores.json기본 TTL: 720시간(30일)
환경 변수:
MGC_STORE_CACHE_PATH
캐시 파일에는 다음 값이 저장됩니다.
refreshedAtcountstores[].storeCodestores[].namestores[].addressstores[].latitudestores[].longitude
이전 방식처럼 매번 전체 매장을 새로 수집하는 대신, 기본적으로 패키지에 포함된 캐시를 우선 사용합니다.
GitHub 배포 사용자는 저장소에 포함된 data/mgc-stores.json을 바로 사용합니다.
MGC_STORE_CACHE_PATH 또는 storeCachePath를 지정하면 해당 경로를 사용자 실행 폴더 기준으로 사용합니다.
전국 재고 조회 내부 흐름:
캐시가 없거나 만료되었으면 전체 매장 리스트 새로 수집
각
store_cd로POST /api/menu/general/list호출item_cd또는 상품명으로 메뉴 검색메뉴가 있으면
sold_out으로 판매 가능/품절 판정메뉴가 없으면
notListed로 분류
실측 예시:
상품명:
와앙 핫 치즈스틱 & 딥상품 코드:
107350수집 매장: 4,286개
상품 노출 매장: 41개
판매 가능: 40개
품절: 1개
품절 매장:
001583송파나루역점
전체 실측 결과 파일:
mgc-cheesestick-national.json
5. MCP 구현 매핑
refresh_mgc_stores
전체 매장 리스트 캐시 갱신 도구입니다.
입력:
{
"cachePath": "data/mgc-stores.json",
"maxStores": 5000
}출력:
cachePathrefreshedAtcountsampleStores
list_mgc_stores_by_region
캐시된 전체 매장 리스트에서 지역 조건에 맞는 매장을 조회합니다.
입력:
{
"regionQuery": "서울 종로구",
"resultLimit": 100
}혜화/대학로권처럼 앱 주소에 행정동이 직접 들어가지 않는 경우:
{
"city": "서울",
"district": "종로구",
"neighborhoods": ["혜화", "대학로"],
"resultLimit": 100
}출력:
totalStoresmatchedStoresstoreCache.fromCachestoreCache.cachePathstoreCache.refreshedAtstores
find_mgc_stores
매장 검색 도구입니다.
입력:
latitudelongitudesigungulimit
소스:
앱 API:
POST /api/store/list보조 소스: 메가MGC커피 공개 웹 매장 조회
출력:
appStores[].storeCodeappStores[].nameappStores[].addressappStores[].latitudeappStores[].longitude
search_mgc_menu
메뉴 검색 도구입니다.
입력:
querylimit
소스:
앱 API:
POST /api/menu/general/list보조 소스: 메가MGC커피 공개 웹 메뉴 조회
출력:
appMenus[].itemCodeappMenus[].nameappMenus[].priceappMenus[].soldOutappMenus[].imageUrl
check_mgc_stock
단일 매장 또는 기본 메뉴 기준 재고 조회 도구입니다.
입력:
productNamestoreCodestoreIdstoreNamesigungulatitudelongitude
소스:
기본:
POST /api/menu/general/list커스텀 연동:
MGC_STOCK_API_URL
판정:
sold_out: false->availablesold_out: true->sold_out메뉴를 찾지 못하면 공개 웹 근거만 반환하며
unknown
check_mgc_stock_nationwide
전국 또는 지역 필터 기반 재고 조회 도구입니다.
입력:
{
"itemCode": "107350",
"productName": "와앙 핫 치즈스틱 & 딥",
"regionQuery": "서울 종로구",
"refreshStores": false,
"storeCacheTtlHours": 720,
"maxStores": 5000,
"concurrency": 8,
"resultLimit": 100
}지역 입력:
regionQuery: 자유형 지역 문자열city: 시/도, 예:서울district: 시/군/구, 예:종로구neighborhoods: 동/도로명/역명/매장명 키워드 배열, OR 조건regionKeyword: 공백 토큰 전체가 매장명/주소에 포함되어야 함regionKeywords: 여러 지역 문구 중 하나라도 매칭되면 포함refreshStores: 재고 조회 전 매장 캐시 강제 갱신storeCachePath: 매장 캐시 파일 경로storeCacheTtlHours: 매장 캐시 TTL. 기본값은 720시간입니다.
regionQuery 해석 규칙:
서울 종로구->서울 AND 종로구서울 종로구 이화동 혜화동->서울 AND 종로구 AND (이화동 OR 혜화동)
소스:
매장 수집:
POST /api/store/list매장별 메뉴 조회:
POST /api/menu/general/list
출력:
checkedStorestotalStoresmatchedStoresmatchedStoreSamplesstoreCachefoundCountavailableCountsoldOutCountnotListedCounterrorsCountavailableStoressoldOutStores
check_mgc_stock_by_region
지역 매장 대상 재고 조회 전용 도구입니다.
서울 종로구 전체 조회:
{
"itemCode": "107350",
"regionQuery": "서울 종로구",
"maxStores": 5000,
"concurrency": 8,
"resultLimit": 100
}서울 종로구의 이화동/혜화동 키워드 조회:
{
"itemCode": "107350",
"city": "서울",
"district": "종로구",
"neighborhoods": ["이화동", "혜화동"],
"maxStores": 5000,
"concurrency": 8,
"resultLimit": 100
}주의:
앱 매장 주소가 행정동 이름을 항상 포함하지는 않습니다.
예를 들어 혜화권 매장이
혜화동대신혜화로,대학로,서울혜화초교점처럼 저장될 수 있습니다.이 경우
neighborhoods에혜화로,대학로,혜화같은 실제 주소/매장명 키워드를 같이 넣으면 됩니다.
6. 설치 및 실행
로컬 설치
npm install
npm run build
node dist/server.js앱 API 베이스 URL을 실행 인자로 바꾸려면:
node dist/server.js \
--app-api-base-url https://app.annhouse.co.kr/api/ \
--app-user-agent okhttp/4.12.0검증:
npm run build
npm test현재 확인 결과:
TypeScript 빌드 통과
Vitest 테스트 통과
checkNationwideStock({ itemCode: "107350", maxStores: 20 })스모크 테스트 통과
Codex에 등록
로컬 저장소에서 설치한 경우 다음 명령으로 Codex MCP 설정에 바로 등록할 수 있습니다.
npm run codex:install이 명령은 빌드 후 아래와 같은 Codex 등록을 자동 실행합니다.
codex mcp add mgc-mcp -- node <현재 패키지>/dist/server.js이미 같은 이름의 MCP 서버가 있으면 npm run codex:install은 기존 mgc-mcp 등록을 제거한 뒤 다시 추가합니다.
수동으로 등록하려면 다음 명령을 사용합니다.
codex mcp add mgc-mcp -- node C:/Users/sh953/Documents/code/active/MGC_MCP/dist/server.js등록 확인:
codex mcp get mgc-mcp
codex mcp list서버 실행 인자를 함께 등록하려면 -- 뒤에 mgc-mcp 인자를 붙입니다.
node dist/codexInstall.js --force -- \
--app-api-base-url https://app.annhouse.co.kr/api/ \
--app-user-agent okhttp/4.12.0다른 이름으로 등록하려면:
node dist/codexInstall.js --name mgc-mcp-dev --forceGitHub 저장소를 직접 설치해서 Codex에 등록하려면:
npx -y --package github:maskelog/MGC_MCP mgc-mcp-install-codex --forceGitHub 설치 방식에서도 저장소의 data/mgc-stores.json이 패키지에 포함됩니다.
따라서 사용자는 별도 캐시 생성 없이 바로 지역 재고 조회를 실행할 수 있습니다.
특정 브랜치나 태그를 고정하려면:
npx -y --package github:maskelog/MGC_MCP#main mgc-mcp-install-codex --force7. MCP 설정 예시
Codex 등록 도우미를 사용하지 않고 MCP 설정 JSON을 직접 작성해야 하는 클라이언트에서는 다음 형태를 사용합니다.
{
"mcpServers": {
"mgc-mcp": {
"command": "node",
"args": ["C:/Users/sh953/Documents/code/active/MGC_MCP/dist/server.js"]
}
}
}커스텀 재고 API를 우선 사용하려면:
{
"mcpServers": {
"mgc-mcp": {
"command": "node",
"args": ["C:/Users/sh953/Documents/code/active/MGC_MCP/dist/server.js"],
"env": {
"MGC_STOCK_API_URL": "https://example.internal/mgc-stock"
}
}
}
}앱 API 베이스 URL을 바꾸려면:
{
"mcpServers": {
"mgc-mcp": {
"command": "node",
"args": ["C:/Users/sh953/Documents/code/active/MGC_MCP/dist/server.js"],
"env": {
"MGC_APP_API_BASE_URL": "https://app.annhouse.co.kr/api/",
"MGC_APP_USER_AGENT": "okhttp/4.12.0"
}
}
}
}실행 인자로 앱 API 베이스 URL을 바꾸려면:
{
"mcpServers": {
"mgc-mcp": {
"command": "node",
"args": [
"C:/Users/sh953/Documents/code/active/MGC_MCP/dist/server.js",
"--app-api-base-url",
"https://app.annhouse.co.kr/api/",
"--app-user-agent",
"okhttp/4.12.0"
]
}
}
}캐시를 사용자 작업 폴더에 따로 저장하고 싶으면:
{
"mcpServers": {
"mgc-mcp": {
"command": "npx",
"args": [
"-y",
"github:maskelog/MGC_MCP"
],
"env": {
"MGC_STORE_CACHE_PATH": "data/mgc-stores.json"
}
}
}
}8. 캡처 및 분석 메모
ADB 확인:
연결 단말:
R3CY10A8WCN앱 패키지:
co.kr.waldlust.megacoffee메인 액티비티:
co.kr.waldlust.megacoffee/.ui.main.MainActivity
APK 분석에서 확인한 항목:
MegaApi.smaliGeneralMenuRequestStoreInfoRequestMegaOrderOptionRequest메뉴 응답 모델의
item_cd,item_nm,sold_out
생성/보관된 작업 파일:
apk/base.apkmgc-current.pngmgc-product-detail.pngmgc-cheesestick-national.json
9. 실패 대응
401/403또는 앱 API 실패
앱 최신 버전에서 헤더, 베이스 URL, 세션 요구 여부 재확인
MGC_APP_USER_AGENT를 실제 앱 User-Agent로 조정
메뉴가 전역 조회에서는 보이지만 매장별 조회에서 없음
해당 매장 메뉴에 상품이 노출되지 않은 상태일 수 있음
이 경우 MCP는
notListed로 집계
상품명이 오타인 경우
가능한 경우
itemCode를 우선 사용예:
와앙 핫 치즈스틱 & 딥->107350
전국 조회가 오래 걸리는 경우
maxStores를 낮춰 부분 검증concurrency를 4~12 범위에서 조정기본값은
concurrency: 8
결과가 너무 큰 경우
resultLimit로 반환 매장 수 제한집계 수치(
checkedStores,foundCount,soldOutCount)는 제한 없이 계산됨
Available Tools
7 toolscheck_mgc_stockCheck Mega MGC Coffee stockB
Check stock for a Mega MGC Coffee menu item. Without MGC_STOCK_API_URL this returns public-site evidence with unknown stock status.
Inputs: productName (required), sigungu, storeId, latitude, +3 more.
check_mgc_stock_by_regionCheck Mega MGC Coffee stock by regionA
Check Mega MGC Coffee app API sold_out values only for stores matching a region query. Example: 서울 종로구 or 서울 종로구 이화동 혜화동.
Inputs: city, district, itemCode, maxStores, +8 more.
check_mgc_stock_nationwideCheck Mega MGC Coffee stock nationwide or by regionB
Check Mega MGC Coffee app API sold_out values across stores nationwide or filtered by region. Use itemCode for exact lookup when known.
Inputs: city, district, itemCode, maxStores, +10 more.
find_mgc_storesFind Mega MGC Coffee storesB
Find Mega MGC Coffee stores by latitude/longitude or Korean sigungu name.
Inputs: limit, sigungu, latitude, longitude.
list_mgc_stores_by_regionList cached Mega MGC Coffee stores by regionB
List stores from the local cache by region. Refreshes cache automatically if missing or expired.
Inputs: city, district, regionQuery, resultLimit, +6 more.
refresh_mgc_storesRefresh Mega MGC Coffee store cacheB
Fetch all Mega MGC Coffee app stores and save them to the local JSON cache.
Inputs: cachePath, maxStores.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Most tools have distinct purposes: stock checking split by scope (public site vs app, regional vs nationwide) and store listing split by search method (lat/lng vs region from cache). However, 'check_mgc_stock' and 'check_mgc_stock_by_region' could be confused if users don't read descriptions carefully, and 'find_mgc_stores' vs 'list_mgc_stores_by_region' have overlapping outputs.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., 'check_mgc_stock', 'find_mgc_stores', 'search_mgc_menu'). The naming is predictable and easy to understand.
With 7 tools, the set is well-scoped for the domain of checking stock and finding stores for a coffee chain. Each tool serves a clear purpose without unnecessary duplication.
The tool set covers core operations: stock checking via multiple methods, store finding, menu search, and cache refresh. Minor gaps exist, such as no tool to retrieve store details (hours, address) or update stock, but these are not essential for a read-only consumer service.
Maintenance
Related MCP Connectors
Search Korean places and read reviews from Naver Map and Kakao Map. Pay per result via Apify.
Real-time Google Maps local business places, reviews, geocoding & contact emails MCP ($0.20/1K).
Korea-native MCP gateway: Korean commerce, payments, messaging, gov & finance APIs for AI agents.
Open places, menus, ratings and booking routes in 119 travel destinations. Read-only, no key needed.
Related MCP Servers
- AlicenseNot gradedqualityNot gradedmaintenanceConnects AI models to real-time search and inventory data for major South Korean retail chains, convenience stores, and cinemas. It enables users to check product availability at stores like Daiso and Olive Young, or view movie schedules at CGV and Megabox.170 npm-
- FlicenseNot gradedqualityDmaintenanceEnables coffee shop order management via MCP, including menu lookup, order creation, and status tracking.-
- AlicenseAqualityDmaintenanceA read-only MCP server that wraps the coffee.pryzm.gg public API to calculate effective prices of coffee drinks after discounts, enabling users to find the cheapest coffee deals, search for discounts, and verify receipt prices.32MIT
- FlicenseNot gradedqualityDmaintenanceEnables gift recommendations via Naver Shopping and nearby pickup store search via Kakao Local APIs.-