MCP Product Search Server

A product search server based on the Model Context Protocol (MCP), allowing Claude to retrieve product catalogs based on keywords and return structured data.

Features

Provides three tools for Claude to call:

Related MCP server: armls-spark-mcp-server

Quick Start

1. Clone the project

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

2. Create a virtual environment and install dependencies

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]"

Requires Python 3.10 or higher. You can check with python3 --version.

3. Test in the browser

mcp dev server.py

The browser will automatically open the MCP Inspector. If it does not open automatically, manually visit the address output in the terminal (usually http://localhost:6274).

Connection Steps:

1. Change the Command on the left to the absolute path of the Python executable in your virtual environment:

   • macOS/Linux: /absolute/path/to/mcp-product-search/.venv/bin/python

   • Windows: C:\absolute\path\to\mcp-product-search\.venv\Scripts\python.exe

2. Fill in server.py for Arguments

3. Click Connect. If the bottom left shows Connected, it is successful

4. Click the Tools tab at the top, select a tool, fill in the parameters, and click Run Tool

4. Integrate with Claude Desktop

Locate the configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following content (replace with the actual absolute path):

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

To view the absolute path of the current directory:

# macOS / Linux
pwd

# Windows
cd

After saving the configuration file, completely exit and restart Claude Desktop.

5. Integrate with Claude Code (CLI)

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

Usage Examples

After connecting to Claude, you can ask questions like:

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

Claude will automatically determine which tool to call and provide an answer based on the returned structured data.

Tool Parameter Description

search

Results are sorted by rating (descending) and price (ascending).

Return Example:

{
  "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

No parameters. Returns all category names and their corresponding product counts.

get_product

Project Structure

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

Extending Product Data

The current product catalog consists of 12 sample items written in products.py. To replace it with real data, simply modify the search_products() function; server.py does not need to be changed.