MCP 제품 검색 서버

Model Context Protocol (MCP) 기반의 제품 검색 서버로, Claude가 키워드를 기반으로 제품 카탈로그를 검색하고 구조화된 데이터를 반환할 수 있게 합니다.

기능

Claude가 호출할 수 있는 세 가지 도구를 제공합니다:

도구	설명
`search`	키워드로 제품 검색, 카테고리, 가격, 평점 필터링 지원
`list_categories`	모든 제품 카테고리 및 수량 나열
`get_product`	ID로 단일 제품의 전체 정보 조회

빠른 시작

1. 프로젝트 복제

git clone <your-repo-url>
cd mcp-product-search

2. 가상 환경 생성 및 의존성 설치

macOS / Linux:

python3 -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]"

Windows:

python -m venv .venv
.venv\Scripts\activate
pip install "mcp[cli]"

Python 3.10 이상이 필요합니다. python3 --version으로 확인할 수 있습니다.

3. 브라우저에서 테스트

mcp dev server.py

브라우저가 자동으로 MCP Inspector를 엽니다. 자동으로 열리지 않으면 터미널에 출력된 주소(보통 http://localhost:6274)로 수동 접속하세요.

연결 단계:

왼쪽 Command를 가상 환경 내 Python의 절대 경로로 변경합니다:
- macOS/Linux: /절대경로/mcp-product-search/.venv/bin/python
- Windows: C:\절대경로\mcp-product-search\.venv\Scripts\python.exe
Arguments에 server.py를 입력합니다.
Connect를 클릭하고 왼쪽 하단에 Connected가 표시되면 성공입니다.
상단 Tools 탭을 클릭하여 도구를 선택하고, 매개변수를 입력한 뒤 Run Tool을 클릭합니다.

4. Claude Desktop에 연결

설정 파일을 찾습니다:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

다음 내용을 추가합니다(실제 절대 경로로 대체하세요):

{
  "mcpServers": {
    "product-search": {
      "command": "/绝对路径/mcp-product-search/.venv/bin/python",
      "args": ["/绝对路径/mcp-product-search/server.py"]
    }
  }
}

현재 디렉토리의 절대 경로 확인:

# macOS / Linux
pwd

# Windows
cd

설정 파일을 저장한 후, Claude Desktop을 완전히 종료하고 재시작하세요.

5. Claude Code(명령줄)에 연결

claude mcp add product-search \
  /绝对路径/mcp-product-search/.venv/bin/python \
  /绝对路径/mcp-product-search/server.py

사용 예시

Claude에 연결한 후 다음과 같이 질문할 수 있습니다:

帮我搜索苹果品牌的笔记本电脑
找一款评分 4.8 以上、价格不超过 300 美元的耳机
列出所有产品分类
查询产品 P003 的详细信息

Claude는 자동으로 어떤 도구를 호출할지 판단하고, 반환된 구조화된 데이터를 기반으로 답변을 제공합니다.

도구 매개변수 설명

`search`

매개변수	타입	필수	기본값	설명
`keyword`	string	예	—	제품명, 설명, 브랜드, 카테고리 및 태그 매칭
`category`	string	아니오	—	카테고리별 필터링 (예: `"Laptops"`, `"Headphones"`)
`max_price`	float	아니오	—	최고 가격 (USD)
`min_rating`	float	아니오	—	최저 평점 (0–5)
`limit`	int	아니오	`10`	결과 개수 제한 (최대 50)

결과는 평점 내림차순, 가격 오름차순으로 정렬됩니다.

반환 예시:

{
  "keyword": "apple",
  "filters": { "category": "Laptops", "max_price": null, "min_rating": null },
  "total_results": 1,
  "products": [
    {
      "id": "P001",
      "name": "Apple MacBook Pro 14-inch M3",
      "category": "Laptops",
      "brand": "Apple",
      "price": 1999.0,
      "currency": "USD",
      "stock": 42,
      "rating": 4.8,
      "description": "14-inch Liquid Retina XDR display, M3 chip, 18GB RAM, 512GB SSD.",
      "tags": ["laptop", "apple", "macbook", "m3", "professional", "portable"]
    }
  ]
}

`list_categories`

매개변수 없음. 모든 카테고리 이름과 해당 제품 수량을 반환합니다.

`get_product`

매개변수	타입	필수	설명
`product_id`	string	예	제품 ID (예: `"P001"`, 대소문자 구분 안 함)

프로젝트 구조

mcp-product-search/
├── server.py        # MCP 服务器，定义工具
├── products.py      # 产品目录与搜索逻辑
├── pyproject.toml   # 项目依赖
└── README.md

제품 데이터 확장

현재 제품 카탈로그는 products.py에 작성된 12개의 샘플 데이터입니다. 실제 데이터로 교체하려면 search_products() 함수만 수정하면 되며, server.py는 수정할 필요가 없습니다.

데이터 소스	수정 방법
로컬 JSON/CSV	시작 시 파일을 읽어 `CATALOG` 채우기
SQLite / PostgreSQL	순회 로직을 SQL 쿼리로 대체
이커머스 API	함수 내부에서 HTTP 요청 전송
Elasticsearch	ES 전문 검색 인터페이스 호출

MCP Product Search Server