MCP 服务器

MCP Product Search Server

Enables product search functionality via MCP, allowing Claude to search products by keyword with filters, list categories, and retrieve product details.

README

MCP 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）。

连接步骤：

将左侧 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

MCP Inspector 连接成功示意

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 全文搜索接口