Product Search Server

一个基于 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）。

连接步骤：

1. 将左侧 Command 改为虚拟环境中 Python 的绝对路径：
   • macOS/Linux：/绝对路径/mcp-product-search/.venv/bin/python
   • Windows：C:\绝对路径\mcp-product-search\.venv\Scripts\python.exe
2. Arguments 填 server.py
3. 点击 Connect，左下角显示 Connected 即成功
4. 点击顶部 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 全文搜索接口