# @ebay/npm-public-api-mcp 中文文档

规范地址：https://npmcn.com/package/%40ebay/npm-public-api-mcp/

版本：1\.2\.0
npm 元数据更新时间：2026-10-27T15:41:03.913Z
中文译文更新时间：2026-11-14T07:51:48.943Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40ebay/npm-public-api-mcp
原文对照：https://npmcn.com/package/%40ebay/npm-public-api-mcp/?lang=original
项目主页：https://github.com/eBay/npm-public-api-mcp#readme
源码仓库：https://github.com/eBay/npm-public-api-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：250 kB，37 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：9 个
- 首次发布：2026-02-18T02:44:20.300Z
- 最新版本发布：2026-10-27T15:41:03.403Z
- 近 30 天下载量：2121（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

OpenAPI 支持的 eBay API 的 MCP 服务器

## 安装

```sh
npm install @ebay/npm-public-api-mcp
```

也可以使用：`pnpm add @ebay/npm-public-api-mcp`、`yarn add @ebay/npm-public-api-mcp`、`bun add @ebay/npm-public-api-mcp`

## README

# eBay API MCP 服务器

无缝地将eBay的API集成到你的AI助理工作流程中. 这个 MCP 服务器可以让 Claude Desktop, Cursor, Cline 等AI 工具直接发现并调用 eBay market API.

## 特征

-   🔍 **REST 图表QL API 访问** - 搜索、浏览和调用 REST API( 通过 OpenAPI 规格) 和 GraphQL API( 通过 schema 发现)
-   💬 **自然语言界面** - 描述你想要什么;不需要记住终点
-   🔑 **使用自动符号管理的简化设置** – 只要提供客户端ID和客户端秘密;服务器处理 OAuth 令牌生成并每~2小时刷新一次
-   🗝️ **双向令牌模式** - 公共数据应用符,私人数据的用户符
-   ⚡ **MCP 即时支持** - 加强REST和GraphQL API的AI助手集成

## 先决条件

-   **节点.js 22或以上** - 校验: `node --version`
-   **eBay 开发者账户** - 注册在 [开发者. ebay.com](https://developer.ebay.com/)

## 重要限制

**沙盒环境不支持**

此发布并不正式支持eBay沙盒环境. 虽然 `EBAY_API_ENV` 配置存在,我们现在不支持沙盒.

**生产环境限制**

-   **REST APIs 软件**: 只支持 GET 请求( 只读操作)
-   **图QL API**: 只支持查询操作( 无突变操作)

这个MCP服务器是为安全,只读访问生产eBay数据而设计的. 沙盒支持和写操作可能在未来的发行中被添加.

## 快速启动

选择最适合您的设置选项 :

-   **备选案文A(建议):** 使用已公布的 npm 软件包——不需要构建步骤
-   **备选案文B:** 克隆和从源头构建——如果想要修改或贡献给服务器,则有用

* * *

### 备选案文A:使用已公布npm软件包(建议)

直接跳到获得证书——不需要建设步骤.

#### 步骤1:获得eBay证书

**客户ID 保密( C) :**

-   从 : [开发者.ebay.com/my/键](https://developer.ebay.com/my/keys)

**所需范围:**

-   取决于您需要访问的 API
-   参考: [OAuth 范围文档](https://developer.ebay.com/api-docs/static/oauth-scopes.html)

**刷新托肯( 可选的, 只用于用户托肯模式) :**

-   参考: [OAuth 授权代码](https://developer.ebay.com/api-docs/static/oauth-auth-code-grant-request.html)

#### 步骤2: 配置您的 MCP 客户端

将此配置添加到您的 MCP 客户端的配置文件 。 服务器运行通过 `npx` 不需要安装或建造步骤.

**用户token模式(用于访问私人用户数据):**

```json
{
  "mcpServers": {
    "ebay-api": {
      "command": "npx",
      "args": ["-y", "@ebay/npm-public-api-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_TOKEN_TYPE": "user",
        "EBAY_REFRESH_TOKEN": "your_refresh_token",
        "EBAY_API_ENV": "production"
      }
    }
  }
}
```

**说明:** 在 User Token 模式中,范围从您刷新的符号中继承 。 您不需要配置 `EBAY_REQUIRED_SCOPES`。 。 。 .

**Token 模式( 用于访问公共数据):**

```json
{
  "mcpServers": {
    "ebay-api": {
      "command": "npx",
      "args": ["-y", "@ebay/npm-public-api-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_REQUIRED_SCOPES": "your_required_scopes",
        "EBAY_TOKEN_TYPE": "application",
        "EBAY_API_ENV": "production"
      }
    }
  }
}
```

**说明:** `EBAY_REQUIRED_SCOPES` 是可选的;省略为默认为 `https://api.ebay.com/oauth/api_scope`。 。 。 .

**克劳德代码 :**

使用 `claude mcp add` 以注册服务器。 使用 `--scope user` 用于所有项目或 `--scope project` 仅用于当前项目.

用户托肯模式 :

```bash
claude mcp add --scope user ebay-api \
  -e EBAY_CLIENT_ID=your_client_id \
  -e EBAY_CLIENT_SECRET=your_client_secret \
  -e EBAY_TOKEN_TYPE=user \
  -e EBAY_REFRESH_TOKEN=your_refresh_token \
  -e EBAY_API_ENV=production \
  -- npx -y @ebay/npm-public-api-mcp
```

应用程序托肯模式 :

```bash
claude mcp add --scope user ebay-api \
  -e EBAY_CLIENT_ID=your_client_id \
  -e EBAY_CLIENT_SECRET=your_client_secret \
  -e EBAY_TOKEN_TYPE=application \
  -e EBAY_REQUIRED_SCOPES=your_required_scopes \
  -e EBAY_API_ENV=production \
  -- npx -y @ebay/npm-public-api-mcp
```

#### 步骤 3: 重新启动您的 MCP 客户端

重新启动您的 MCP 客户端以装入服务器 .

* * *

### 备选方案B:从来源建立

如果您想要修改服务器或为工程做出贡献, 请使用此选项 .

#### 步骤1:克隆和构建

```bash
git clone https://github.com/eBay/npm-public-api-mcp.git
cd npm-public-api-mcp

# Install dependencies and build
npm install
npm run build
```

**所需经费:** 节点.js 22+

#### 第2步:获得eBay证书

与备选案文A相同——见 [步骤1](https://npmcn.com/package/%40ebay/npm-public-api-mcp/#readme-step-1-get-ebay-credentials) 见上文.

#### 步骤 3: 配置您的 MCP 客户端

与备选案文A相同,但替换 `command` 财务报告和审定财务报表 `args` 使用您的本地建构路径 :

```json
"command": "node",
"args": ["/absolute/path/to/npm-public-api-mcp/dist/index.js"]
```

克劳德代码,替换 `-- npx -y @ebay/npm-public-api-mcp` 与 `-- node /absolute/path/to/npm-public-api-mcp/dist/index.js`所有环境变量保持不变.

#### 步骤 4: 重新启动您的 MCP 客户端

重新启动您的 MCP 客户端以装入服务器 .

## 配置参考

| 变量 | 需求 | 说明 |
| --- | --- | --- |
| `EBAY_CLIENT_ID` | 对 | eBay 应用程序客户端标识 |
| `EBAY_CLIENT_SECRET` | 对 | eBay 应用程序客户端机密 |
| `EBAY_TOKEN_TYPE` | 没有 | `"application"` (违约)或 `"user"` |
| `EBAY_REFRESH_TOKEN` | 有条件 | 需要时间 `EBAY_TOKEN_TYPE="user"` |
| `EBAY_REQUIRED_SCOPES` | 没有 | 授权范围(应用) 仅托肯模式). 对于多范围,将其与空间相分离,例如, `"https://api.ebay.com/oauth/api_scope https://api.ebay.com/oauth/api_scope/sell.inventory"` |
| `EBAY_API_ENV` | 没有 | `"production"` (不支持对话框) |

## 工具和提示

这台服务器向您的AI助手披露了4个主工具和2个MCP提示.

### `query_ebay_api` ——REST API发现

使用自然语言来搜索eBay的OpenAPI规格. 用此来探索可用的 API, 查找端点参数, 或找到合适的 API 任务 .

```
Find eBay APIs related to product listings
What parameters does the Browse API's getItem endpoint require?
Which API should I use to search for items by keyword?
```

### `call_ebay_api` - 重新召集API

执行实际调用eBay的API并返回活市场数据. 一般使用于 `query_ebay_api` 确定了正确的终点.

```
Search for iPhone 15 listings on eBay and show me the top 5 results
Get details for eBay item ID 123456789
Show me eBay's taxonomy categories for electronics
```

### `query_ebay_graphql` ——图QL Schema发现

使用自然语言提示搜索 eBay 的 GraphQL 计划 。 以此来探索可用的查询,变异,类型,和字段,或者找到一个任务的正确操作.

```
What fields are available on the Order type?
Which query should I use to get item details by ID?
What mutations are available for managing listings?
```

### `call_ebay_graphql` ——图QL 查询执行

执行针对 eBay API 的实际 GraphQL 查询并返回活市场数据 。 一般使用于 `query_ebay_graphql` 确定了正确的行动及其所需的领域.

```
Get the title, price, and seller info for listing ID 123456789
Search for iPhone 15 items and return the top 5 with prices
Fetch my active orders and their current status
```

您可以用自然语言询问——AI自动选择和排序工具.

## MCP 提示

这个服务器注册了两个MCP提示来帮助客户端将广泛的用户请求转换成正确的工具呼叫——一个用于REST APIs,一个用于GraphQL.

### `interpret_user_request` 请求解释

接受用户的原始请求为 `user_input` 并返回帮助 MCP 客户端决定何时使用的指导 `query_ebay_api`,何时使用 `call_ebay_api`,以及如何表达发现查询.

典型的使用情况:

-   将抽象请求转换为具体的 eBay REST API 动作
-   决定先搜索API规格还是直接引用已知的终点
-   改进发送到 `query_ebay_api`

### `interpret_graphql_request` - 图QL 请求解释

接受用户的原始请求为 `user_input` 并返回帮助 MCP 客户端决定何时使用的指导 `query_ebay_graphql`,何时使用 `call_ebay_graphql`如何接近计划发现.

典型的使用情况:

-   将抽象请求转换为特定的 eBay GraphQL 操作
-   决定先探索计划还是直接执行已知查询
-   改进发送到 `query_ebay_graphql`

### 如何使用这些提示

| 提示 | 克劳德代码 | GitHub 副驾驶 |
| --- | --- | --- |
| 资源 | `/ebay-api:interpret_user_request` | `/mcp.ebay-api.interpret_user_request` |
| 图QL | `/ebay-api:interpret_graphql_request` | `/mcp.ebay-api.interpret_graphql_request` |

即时支持取决于MCP客户端集成. 如果提示没有被曝光,请直接使用工具.

## 用法实例

一旦连接,请用自然语言询问您的AI助手:

**说明**:您不需要指定是否想要 REST 或 GraphQL —— MCP 既探索又自动选择最合适的 API.

-   **"寻找上市产品的 eBay API"** 搜索 REST 和 GraphQL API
-   **"我需要什么范围权限才能进入我的观察名单?"** 检查所需的 OAuth 瞄准镜
-   **"使用用户SavedSearches可以查询什么信息?"** 探索GraphQL计划
-   **"获取IDORD-001和ORD-002的详细订单"** ——执行真正的API呼叫

## OAuth 认证模式

| 模式 | 使用大小写 | 所需资源 |
| --- | --- | --- |
| **用户键** | 私人用户数据(库存、订单、账户信息) | 客户端ID,客户端秘密,刷新托肯——从刷新符所继承的范围 |
| **应用程序** | 公共市场数据 | 客户身份、客户秘密、可选 `EBAY_REQUIRED_SCOPES` |

两种模式都自动处理令牌刷新 。 关于每个模式后面的 OAuth 流量,见 [授权代码](https://developer.ebay.com/api-docs/static/oauth-auth-code-grant-request.html) 财务报告和审定财务报表 [客户证书赠款](https://developer.ebay.com/api-docs/static/oauth-client-credentials-grant.html)。 。 。 .

## 安保最佳做法

### 保护您的全权证书

-   QQ 从不将证书输入版本控制
-   使用环境变量或安全金库进行生产
-   QQ 定期旋转客户端机密

### 托肯安保系统

-   刷新符号是长寿的——安全保存
-   应用程序符号在~2小时后自动过期(服务器处理刷新)
-   永远不要公开或用截图分享令牌

## \* 解决问题

**MCP 服务器不显示 :**

-   如果使用选项A(npx):验证您的节点.js版本为22+,并且 `npx` 可用
-   如果使用选项B( 源构建): 验证 `dist/index.js` 已存在( 运行) `npm run build`)并检查配置中的绝对路径
-   重新启动您的 MCP 客户端

**认证失败( 401 ) :**

-   核查证书无误
-   对于应用程序令牌模式,请检查 `EBAY_REQUIRED_SCOPES` 包括必要的权限
-   对于用户令牌模式,确保刷新令牌有效

**Token 检索失败( IDE 从 GUI 启动) :**

-   从GUI所推出的IDE(如:VS代码,光标)可能不会继承 shell 环境变量,导致证书未解决并令牌请求失败.
-   **修复( 快速):** 在配置文件中直接对证书值进行硬码——只是不要将其用于版本控制.
-   **修补( 备选) :** 从终端启动您的 IDE, 这样它就能继承 shell 环境 。 VS代码和光标在命令调色板上一次性安装CLI后,在本地支持这个.

**API 调用失败 :**

-   校验您是否使用生产环境
-   只使用 RESTGET 请求或 GraphQL 查询操作; 不支持写入操作
-   检查您的 eBay 账户是否有所需的 API 访问权限

## 发布注释 (v1.2.0)

如果您先前使用过此 MCP 服务器的更早版本, 此版本中添加的内容 :

-   **图QL API 支持** - 在现有 REST API 支持的同时, 添加计划发现和查询执行
-   **图QL MCP 提示** - 添加数 `interpret_graphql_request` 与现有的 REST API 提示

## 资源

-   🔐 **[获取 eBay 证书](https://developer.ebay.com/my/keys)** - 客户身份和秘密
-   📚 **[eBay API 文档](https://developer.ebay.com/)** - 完整的API参考文献
-   🔧 **[MCP 议定书](https://modelcontextprotocol.io/)** - 学习MCP

**测试愉快**

## 许可证

Apache 2. 0 - 见 [自由主义](https://github.com/eBay/npm-public-api-mcp/blob/main/LICENSE.txt) 更多信息.

## 常见问题

### @ebay/npm-public-api-mcp 是什么？

OpenAPI 支持的 eBay API 的 MCP 服务器

### 如何安装 @ebay/npm-public-api-mcp？

在项目目录运行 npm install @ebay/npm-public-api-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 ebay-mcp-server，可以用 npx ebay-mcp-server 直接运行。

### @ebay/npm-public-api-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/ebay\_\_npm-public-api-mcp 是否存在。

### @ebay/npm-public-api-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @ebay/npm-public-api-mcp 可以商用吗？

@ebay/npm-public-api-mcp 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @ebay/npm-public-api-mcp 的下载量有多少？

根据 npm 官方下载统计，@ebay/npm-public-api-mcp 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,121 次，日均约 71 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @ebay/npm-public-api-mcp 还在维护吗？

最新版本 1\.2\.0 发布于 2026/10/27（17 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/02/18。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。