Model Context Protocol (MCP) 기반의 제품 검색 서버로, Claude가 키워드를 기반으로 제품 카탈로그를 검색하고 구조화된 데이터를 반환할 수 있게 합니다.
Claude가 호출할 수 있는 세 가지 도구를 제공합니다:
도구 | 설명 |
| 키워드로 제품 검색, 카테고리, 가격, 평점 필터링 지원 |
| 모든 제품 카테고리 및 수량 나열 |
| ID로 단일 제품의 전체 정보 조회 |
Related MCP server: MCP Merchant Scout
git clone <your-repo-url>
cd mcp-product-searchmacOS / 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으로 확인할 수 있습니다.
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을 클릭합니다.
설정 파일을 찾습니다:
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을 완전히 종료하고 재시작하세요.
claude mcp add product-search \
/绝对路径/mcp-product-search/.venv/bin/python \
/绝对路径/mcp-product-search/server.pyClaude에 연결한 후 다음과 같이 질문할 수 있습니다:
帮我搜索苹果品牌的笔记本电脑
找一款评分 4.8 以上、价格不超过 300 美元的耳机
列出所有产品分类
查询产品 P003 的详细信息Claude는 자동으로 어떤 도구를 호출할지 판단하고, 반환된 구조화된 데이터를 기반으로 답변을 제공합니다.
search매개변수 | 타입 | 필수 | 기본값 | 설명 |
| string | 예 | — | 제품명, 설명, 브랜드, 카테고리 및 태그 매칭 |
| string | 아니오 | — | 카테고리별 필터링 (예: |
| float | 아니오 | — | 최고 가격 (USD) |
| float | 아니오 | — | 최저 평점 (0–5) |
| int | 아니오 |
| 결과 개수 제한 (최대 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매개변수 | 타입 | 필수 | 설명 |
| string | 예 | 제품 ID (예: |
mcp-product-search/
├── server.py # MCP 服务器，定义工具
├── products.py # 产品目录与搜索逻辑
├── pyproject.toml # 项目依赖
└── README.md현재 제품 카탈로그는 products.py에 작성된 12개의 샘플 데이터입니다. 실제 데이터로 교체하려면 search_products() 함수만 수정하면 되며, server.py는 수정할 필요가 없습니다.
데이터 소스 | 수정 방법 |
로컬 JSON/CSV | 시작 시 파일을 읽어 |
SQLite / PostgreSQL | 순회 로직을 SQL 쿼리로 대체 |
이커머스 API | 함수 내부에서 HTTP 요청 전송 |
Elasticsearch | ES 전문 검색 인터페이스 호출 |
Retrieve full details for a single product by its ID (e.g. "P001").
Args: product_id: The product's unique identifier.
| Name | Required | Description | Default |
|---|---|---|---|
| product_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist; description implies read-only but fails to disclose any behavioral details beyond 'retrieve'.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loading the core purpose and listing the parameter clearly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple single-parameter input and presence of an output schema, the description is sufficiently complete for the task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaning to the product_id parameter with an example and context, compensating for 0% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves full details for a single product by ID, distinguishing it from siblings like list_categories and search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus siblings like search or list_categories is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return all available product categories and their item counts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only states the basic return value, omitting additional behavioral details such as ordering, limits, or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, clear sentence with no unnecessary words, perfectly front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read operation with no parameters and an output schema present, the description sufficiently covers what the tool returns.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Since there are no parameters, the description does not need to add parameter information. Baseline 4 for 0 parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb 'Return' and resource 'all available product categories and their item counts', distinguishing it from sibling tools like 'get_product' and 'search'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'search' or 'get_product', leaving the agent to infer context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search products by keyword with optional filters.
Args: keyword: Search term matched against name, description, brand, category, and tags. category: Filter by exact category name (e.g. "Laptops", "Headphones"). max_price: Upper price limit in USD. min_rating: Minimum rating (0–5). limit: Maximum number of results to return (default 10, max 50).
| Name | Required | Description | Default |
|---|---|---|---|
| keyword | Yes | ||
| category | No | ||
| max_price | No | ||
| min_rating | No | ||
| limit | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that keyword matches multiple fields (name, description, brand, category, tags) and explains filters, but does not mention that the operation is read-only, result ordering, or error behavior. Adequate but missing some context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear introductory sentence followed by structured 'Args' bullet points. It front-loads the purpose and efficiently details parameters without unnecessary text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and existence of an output schema, the description covers input well but omits output format details. It could mention response structure or behavior like empty results. Acceptable but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It fully explains each parameter beyond the schema: keyword matches specific fields, category is exact name, max_price is in USD, min_rating is 0-5, limit has default and max. This adds significant meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Search products by keyword with optional filters.' It specifies the verb 'search' and the resource 'products', distinguishing it from sibling tools 'get_product' (retrieves a single product) and 'list_categories' (lists categories).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for searching products but does not explicitly contrast with siblings or provide when-not-to-use guidance. The context is clear from names, but the description lacks explicit exclusions or alternative recommendations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_productlist_categoriessearchScored across 3 tools
Each tool has a distinct purpose: get_product retrieves by ID, list_categories returns category overview, search does keyword-based filtering. No ambiguity in their roles.
All tool names follow a consistent verb_noun pattern (get_product, list_categories, search) using snake_case, making them predictable.
With 3 tools, the server is well-scoped for a search-focused service. Each tool earns its place without bloat or deficiency.
The tool set covers core search and retrieval operations (get by ID, list categories, keyword search). Missing a general 'list all products' operation, but search likely covers this with an empty keyword, though not documented; minor gap.
AMZScout Skill + MCP gives AI agents live access to real Amazon marketplace data across 14 Amazon marketplaces. Analyze any ASIN, validate product ideas, research niches, compare competitors, discover profitable keywords, and build data-driven PPC strategies using trusted Amazon insights instead of AI assumptions. Works with Claude, ChatGPT, Cursor, and any other MCP-compatible AI client. To connect, you'll need an AMZScout API plan and authorize your account. Get access and view pricing here: https://learn.amzscout.net/amazon-product-api-for-ai-agents
Search multi-merchant supply, checkout, and track orders via MCP.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Connect Amazon Seller Central to Claude or ChatGPT via MCP. Orders, inventory, pricing, fees, FBA.
