金大哥 - secondhand-mcp MCP 详情

article

README

🚀 二手商品MCP

这是一个模型上下文协议（MCP）服务器，可让AI助手搜索二手市场。你可以在Facebook Marketplace、eBay、Depop和Poshmark等平台上搜索二手物品，还能按价格、类别、状况、尺寸和颜色进行筛选，之后获取包含照片、描述和卖家信息的完整商品列表详情。

该服务器可与Claude Desktop、Claude Code、Cursor以及任何兼容MCP的客户端配合使用。

⚠️ 重要提示

若想跳过设置步骤，可尝试二手商品MCP云服务，这是一个托管版本，能在30秒内连接到Claude.ai和ChatGPT，无需安装，也不需要Chrome浏览器，还提供免费套餐。

✨ 主要特性

支持多个二手交易平台的搜索，包括Facebook Marketplace、eBay、Depop和Poshmark。
可根据多种条件进行筛选，如价格、类别、状况、尺寸和颜色等。
能获取商品的完整详情，包含照片、描述和卖家信息。
与Claude Desktop、Claude Code、Cursor等MCP兼容客户端集成。

📦 安装指南

Claude Desktop

将以下内容添加到 ~/Library/Application Support/Claude/claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "secondhand": {
      "command": "npx",
      "args": ["-y", "secondhand-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your-ebay-client-id",
        "EBAY_CLIENT_SECRET": "your-ebay-client-secret"
      }
    }
  }
}

Claude Code

将以下内容添加到 ~/.claude/.mcp.json 文件中：

{
  "mcpServers": {
    "secondhand": {
      "command": "npx",
      "args": ["-y", "secondhand-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your-ebay-client-id",
        "EBAY_CLIENT_SECRET": "your-ebay-client-secret"
      }
    }
  }
}

eBay、Depop和Poshmark的配置都是可选的。如果缺少eBay API密钥或未安装Chrome浏览器，这些平台将自动禁用，其他平台仍可正常使用。

Depop和Poshmark / Chrome浏览器要求

Depop和Poshmark需要无头浏览器支持。如果系统中安装了 Google Chrome或Chromium，这两个平台将自动启用，无需额外配置。如果未找到Chrome浏览器，它们将被静默跳过。

在macOS系统上，首次搜索Depop或Poshmark时，可能会看到系统提示，询问是否允许Node.js控制Chrome浏览器。这是正常现象，因为puppeteer需要以无头模式启动Chrome浏览器。只需允许一次，之后就不会再提示。

浏览器将在后台以不可见模式运行，仅在实际搜索Depop或Poshmark时启动。

📚 详细文档

配置

选择平台

默认情况下，所有平台均已启用。若要限制启用的平台，可设置 MARKETPLACES 环境变量（以逗号分隔），示例如下：

{
  "env": {
    "MARKETPLACES": "facebook,ebay"
  }
}

有效取值为：facebook、ebay、depop、poshmark。

eBay API密钥

eBay使用官方的浏览API，你需要一个免费的eBay开发者账户。具体步骤如下：

在 developer.ebay.com 上创建一个账户。
创建一个应用程序，获取客户端ID和客户端密钥。
将它们作为 EBAY_CLIENT_ID 和 EBAY_CLIENT_SECRET 添加到MCP配置中。

工具

`search_marketplace`

用于在各个平台上搜索商品，参数说明如下： | 参数 | 是否必需 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | query | 是 | 无 | 搜索关键词 | | marketplace | 否 | facebook | 可选值为 facebook、ebay、depop、poshmark 或 all | | location | 否 | san francisco | 搜索城市（仅适用于Facebook） | | maxPrice | 否 | 无 | 最高价格 | | minPrice | 否 | 无 | 最低价格 | | limit | 否 | 20 | 最大结果数 | | showSold | 否 | false | 是否包含已售商品（仅适用于Facebook） | | includeImages | 否 | false | 输出中是否包含图片URL | | sort | 否 | relevance | 排序方式（适用于Depop和Poshmark），可选值为 relevance、newest、most_popular、price_low_to_high、price_high_to_low | | condition | 否 | 无 | 商品状况。eBay可选值为 new、like_new、good、fair；Depop可选值为 new、like_new、excellent、good、fair、used；Poshmark可选值为 new（NWT）、like_new（NWOT）、good、fair | | category | 否 | 无 | 商品类别。Depop可选值为 tops、bottoms、dresses、coats-jackets、footwear、accessories、bags、jewellery、activewear、swimwear；Poshmark可选值为 Jackets_&_Coats、Dresses、Shoes、Accessories 等 | | brand | 否 | 无 | 品牌筛选（仅适用于Poshmark），例如 "Nike"、"Levi's"、"Gucci" | | department | 否 | 无 | 部门筛选（仅适用于Poshmark），可选值为 Women、Men、Kids | | sizes | 否 | 无 | 尺寸筛选（适用于Depop和Poshmark），例如 ["S", "M", "L"] 或 ["US 9", "US 10"] | | colors | 否 | 无 | 颜色筛选（适用于Depop和Poshmark），可选值为 black、white、red、blue、green、yellow、orange、pink、purple、brown、grey、cream、multi、silver、gold |

各平台返回的数据字段： | 字段 | Facebook | eBay | Depop | Poshmark | | ---- | ---- | ---- | ---- | ---- | | 标题 | 是 | 是 | 是 | 是 | | 价格 | 是 | 是 | 是 | 是 | | 位置 | 城市 | 城市，州 | 无 | 无 | | 状况 | 无 | 是 | 无 | 无 | | 照片数量 | 1张缩略图 | 1张缩略图 | 1张缩略图 | 1张缩略图 | | 卖家 | 是 | 是 | 无 | 无 |

`get_listing_details`

使用搜索结果中的商品ID获取特定商品的完整详情，参数说明如下： | 参数 | 是否必需 | 默认值 | 描述 | | ---- | ---- | ---- | ---- | | listingId | 是 | 无 | 搜索结果中的商品ID | | marketplace | 否 | facebook | 可选值为 facebook、ebay、depop 或 poshmark |

各平台返回的数据字段： | 字段 | Facebook | eBay | Depop | Poshmark | | ---- | ---- | ---- | ---- | ---- | | 描述 | 是 | 是 | 是 | 是 | | 所有照片 | 是 | 是 | 是 | 是 | | 位置 | 城市 | 城市，州，国家 | 无 | 无 | | 卖家 | 姓名 | 用户名 | 用户名 | 用户名 | | 配送方式 | 是 | 无 | 无 | 无 | | 运费 | 是/否 | 服务代码 | 是/否 | 始终包含 |

`list_marketplaces`

列出所有已启用的平台及其状态。

工作原理

Facebook Marketplace：通过位置、价格和查询关键词搜索商品列表，可将城市名称解析为坐标，无需登录或浏览器。
eBay：使用官方eBay浏览API和OAuth 2.0客户端凭证，令牌会被缓存并自动刷新。
Depop：使用无头浏览器搜索商品列表，支持按类别、状况、尺寸和颜色进行筛选，浏览器实例在请求之间共享。
Poshmark：使用无头浏览器搜索商品列表，支持按状况、尺寸、颜色、排序和价格进行筛选，Poshmark不基于位置，所有商品均为全国发货。

开发

git clone https://github.com/jlsookiki/secondhand-mcp.git
cd secondhand-mcp
npm install
npm run build

添加新平台

在 src/marketplaces/ 目录下创建一个新文件。
继承 BaseMarketplace 类，并实现 search() 方法，可选择性实现 getListingDetails() 方法。
将构造函数添加到 src/marketplaces/index.ts 文件的 allMarketplaces 中。

🔧 技术细节

各平台的技术实现

Facebook Marketplace：通过解析城市名称为坐标，利用位置、价格和查询关键词进行搜索，无需登录和浏览器，直接与前端页面交互获取数据。
eBay：使用官方的Browse API和OAuth 2.0客户端凭证进行身份验证和数据请求，令牌会被缓存并自动刷新，以提高性能和减少请求次数。
Depop：使用无头浏览器（如Chrome或Chromium）模拟用户操作，通过页面元素定位和解析来搜索商品列表，支持多种筛选条件。浏览器实例在多个请求之间共享，以提高效率。
Poshmark：同样使用无头浏览器进行页面抓取，支持按多种条件筛选商品。由于没有官方API，主要依赖页面解析技术来提取数据，且不基于位置信息，所有商品均为全国发货。

配置与环境变量

通过配置文件（如 claude_desktop_config.json 和 .mcp.json）来管理MCP服务器的设置，包括服务器命令、参数和环境变量。
环境变量 MARKETPLACES 用于指定要启用的市场平台，EBAY_CLIENT_ID 和 EBAY_CLIENT_SECRET 用于eBay API的身份验证。

代码结构与模块化

项目采用模块化设计，将不同市场平台的实现封装在 src/marketplaces/ 目录下的独立文件中，每个文件继承 BaseMarketplace 类，并实现相应的搜索和详情获取方法。
在 src/marketplaces/index.ts 中统一管理所有市场平台的构造函数，便于扩展和维护。

性能优化与错误处理

对于eBay的API请求，采用令牌缓存和自动刷新机制，减少不必要的身份验证请求，提高性能。
在使用无头浏览器时，通过共享浏览器实例和优化页面解析逻辑，减少资源占用和响应时间。
对于可能出现的错误情况，如缺少API密钥、未安装Chrome浏览器等，进行了相应的处理和提示，确保系统的稳定性和可用性。

🚫 局限性

Facebook：若Facebook更改其前端页面，可能会导致搜索功能失效。
eBay：需要开发者API密钥，不过有免费套餐可供使用。
Depop：需要安装Chrome/Chromium浏览器，搜索速度比Facebook/eBay慢（每次搜索约5秒）。
Poshmark：需要安装Chrome/Chromium浏览器，由于没有官方API，依赖页面抓取技术。
速率限制：请勿过于频繁地发送大量请求。

📄 许可证

本项目采用MIT许可证。

secondhand-mcp