# MCP 接入指南

# 概述

CJ Dropshipping 提供了 MCP（Model Context Protocol，模型上下文协议）服务器，让 AI 助手可以直接调用 CJ 的 API 能力。通过 MCP，您无需手动编写代码，即可在 ChatGPT 、VS Code Copilot 等 AI 平台中，使用自然语言搜索商品、查询订单、管理物流等。

# 什么是 MCP？

MCP（模型上下文协议）是 Anthropic 推出的开放标准协议，允许 AI 模型以标准化方式调用外部工具和服务。CJ MCP 服务器将核心 CJ API 操作封装为一组 AI 客户端可调用的工具。

# 可用工具列表

工具名称	功能描述
`search_products`	按关键词、价格区间、类目等搜索 CJ 商品
`query_sku_details`	查询商品变体详情及价格
`get_order_list`	按状态、时间段或订单号查询订单列表
`get_pay_order_list`	查询待支付订单列表
`create_order`	创建 CJ 订单
`calculate_freight`	计算商品物流运费
`get_logistics_timeliness`	查询目的地物流时效
`get_warehouses`	获取可用仓库列表
`list_shops`	获取已授权店铺列表
`list_disputes`	查询纠纷列表
`get_dispute_detail`	获取纠纷详情
`create_dispute`	发起新纠纷
`cancel_dispute`	取消纠纷
`merge_orders`	合并多个订单
`check_login_status`	检查当前登录状态
`verify_credentials`	使用邮箱和密码登录
`add_to_cart`	添加商品到购物车

# 连接方式

CJ MCP 服务器支持两种连接模式：

模式	传输方式	适用平台
本地模式（stdio）	标准输入输出	VS Code Copilot、Claude Desktop、Cursor 等
远程模式（HTTP）	StreamableHTTP	ChatGPT、任何支持 HTTP 的客户端

# 各平台接入教程

# 1. 本地模式 — VS Code Copilot / Claude / Cursor 等

本节介绍以 stdio（标准输入输出）方式在本地运行 CJ MCP 服务器的统一方法。适用于所有支持本地 MCP APPS 的 AI 客户端：VS Code GitHub Copilot、Claude Desktop、Cursor 等。

# 前置要求

Node.js >= 20.0.0（推荐通过 nvm (opens new window) 管理版本）
任意支持本地 MCP stdio 连接的 AI 客户端

# 第一步：克隆并构建 CJ MCP Server

git clone https://github.com/CJ-dropshipping/api-mcp.git
cd api-mcp
npm install
npm run build

构建完成后，入口文件位于 dist/mcp-server/index.cjs。记录项目的绝对路径（后续配置需要用到）：

# macOS / Linux
pwd
# Windows（PowerShell）
(Get-Location).Path

# 第二步：在 AI 客户端中配置 CJ MCP Server

将 <绝对路径> 替换为第一步获取的路径，按照您使用的 AI 客户端选择对应配置方式：

VS Code（GitHub Copilot）

在任意工作区根目录创建 .vscode/mcp.json：

{
  "servers": {
    "cj-dropshipping": {
      "type": "stdio",
      "command": "node",
      "args": ["<绝对路径>/dist/mcp-server/index.cjs"]
    }
  }
}

Claude Desktop

编辑 Claude Desktop 配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json，Windows：%APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "cj-dropshipping": {
      "command": "node",
      "args": ["<绝对路径>/dist/mcp-server/index.cjs"]
    }
  }
}

Cursor / 其他 MCP APPS

请参考对应客户端的 MCP 配置文档，使用以下信息进行配置：

传输类型：stdio
命令：node
参数：<绝对路径>/dist/mcp-server/index.cjs

可选环境变量

变量名默认值说明

CJ_LOG_LEVEL info 日志级别：debug、info、warn、error

CJ_LOG_FILE false 是否输出日志到文件（true / false）

CJ_LANGUAGE en 语言：en（英文）、zh（中文）

CJ_CURRENCY USD 默认货币

变量名	默认值	说明
`CJ_LOG_LEVEL`	`info`	日志级别：`debug`、`info`、`warn`、`error`
`CJ_LOG_FILE`	`false`	是否输出日志到文件（`true` / `false`）
`CJ_LANGUAGE`	`en`	语言：`en`（英文）、`zh`（中文）
`CJ_CURRENCY`	`USD`	默认货币

# 第三步：首次登录 CJ 账号

配置完成后，通知 AI 客户端加载配置（重启或刷新），然后：

向 AI 发送指令：登录 CJ 账号（或使用 show_login_form 工具）
MCP 服务器会弹出 CJ 登录页面，在页面中输入 CJ 账号和密码
登录成功后，Token 会加密存储在本地 .cj-token 文件，后续无需重复登录

# 使用示例

搜索 "wireless earbuds" 商品
查看我最近的订单
查询订单 DP2605200604000336000 的详情
计算一下这个商品发到美国的运费

# 故障排查

问题	解决方案
工具未出现在客户端中	检查配置文件语法；重启 AI 客户端
`node` 命令未找到	安装 Node.js 20+；确认 `node` 在 PATH 中
登录失败	确认 CJ 账号邮箱/密码正确；检查网络连接
日志查看	设置 `CJ_LOG_FILE=true` 后查看本地日志文件

# 2. ChatGPT（远程 HTTP 模式）

ChatGPT 支持通过 HTTPS 直接连接 CJ 官方 MCP 服务器，无需自建服务器。

# 第一步：获取 CJ API Key

登录 CJ 账号，进入 API Key 管理页面 (opens new window)。
点击生成，创建您的 API Key（如已有可直接使用）。

# 第二步：获取 Access Token

在终端中执行以下 curl 命令，将 YOUR_API_KEY 替换为第一步获取的 API Key：

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/authentication/getAccessToken' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "apiKey": "YOUR_API_KEY"
  }'

请求成功响应示例：

{
  "code": 200,
  "result": true,
  "message": "Success",
  "data": {
    "accessToken": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "accessTokenExpiryDate": "2021-08-18T09:16:33+08:00"
  }
}

复制 accessToken 的值，下一步需要用到。

注意： Access Token 有效期为 180 天。服务器会缓存 Token 24 小时，24 小时内重复请求返回相同的 Token。

# 第三步：在 ChatGPT 中创建 CJ MCP 应用

打开 chatgpt.com (opens new window)，点击左下角设置 → 应用 → 高级设置。
开启 开发者模式。
点击 创建应用。
填写以下信息：
- 名称： 自定义应用名称，例如 CJMCP-ZhangSan
- 描述： 例如 CJ Dropshipping 购物助手
- MCP 服务器 URL： https://developers.cjdropshipping.cn/mcp/YOUR_ACCESS_TOKEN （将 YOUR_ACCESS_TOKEN 替换为第二步获取的 token 值）
- 身份授权： 选择 未授权
同意协议并点击创建，等待应用初始化完成。

# 第四步：在 ChatGPT 中使用 CJ MCP

新建一个对话窗口。
输入 /CJMCP-ZhangSan，从提示列表中选择对应应用。
开始自然语言对话，例如：
- 使用 CJMCP-ZhangSan 看下当前用户信息
- 搜索“手机壳”商品
- 查看我最近的订单

提示： Token 到期（180 天）后，重新执行第一、第二步获取新 Token，并在应用设置中更新 MCP 服务器 URL 即可。

# 多账号使用

如需在多个 CJ 账号之间切换，可以为每个账号单独创建一个应用：

对每个账号分别执行第一、第二步，获取该账号对应的 Access Token。
在第三步创建应用时，填入对应账号的 Token，并使用不同的应用名称（例如 CJMCP-Account1、CJMCP-Account2）。
使用时通过 /应用名称 切换至对应账号的应用即可。

# 更新应用工具列表

当 CJ MCP 服务器新增了工具或功能时，需要手动刷新应用以获取最新的工具列表：

进入 ChatGPT 设置 → 应用，找到已创建的 CJ MCP 应用。
点击应用详情页面中的刷新按钮，等待工具列表更新完成。

# 登录鉴权说明

# 本地模式（VS Code Copilot / Claude / Cursor 等）

CJ MCP 服务器在本地运行时使用基于 Token 的身份验证：

调用 check_login_status 检查是否已登录。
若未登录，调用 verify_credentials 传入 CJ 邮箱和密码。
Token 会加密存储在本地 — 下次启动无需重新登录。

安全说明： 您的账号信息仅用于从 CJ 官方 API 获取 Access Token。Token 以加密形式存储在您的本地设备上，不会传输给任何第三方。

# ChatGPT

ChatGPT 的身份认证通过嵌入 MCP 服务器 URL 中的 Access Token 完成（见上方第 2 节 ChatGPT 接入第二步）。无需在对话中单独进行登录操作。

# 验证配置

配置完成后，在您的 AI 客户端中输入以下内容进行验证：

检查我的 CJ 登录状态
搜索 "手机壳" 商品
查询我最近的订单

如果配置正确，AI 将调用相应的 MCP 工具并返回结果。

# 常见问题

问题	解决方案
工具未出现在 AI 客户端中	重启 AI 客户端；检查配置文件语法是否正确
鉴权失败	验证 CJ 邮箱/密码；检查 CJ 账号权限
远程 MCP 连接失败	确认服务器正在运行；检查防火墙规则和 SSL 证书
工具调用超时	增大 nginx `proxy_read_timeout`；检查网络连接
`npx` 命令未找到	从 nodejs.org (opens new window) 安装 Node.js 18+

← 接口调用限制接口定义 →