Content
# CJ Dropshipping MCP Server
CJ Dropshipping's MCP (Model Context Protocol) server enables AI assistants to directly call CJ's API capabilities. Supports operations such as product search, order management, and logistics inquiry through natural language in AI platforms like VS Code GitHub Copilot, ChatGPT, and more.
## Features
- 🛒 **Product Operations** — Search products, view details, query inventory and variations
- 📦 **Order Management** — Create orders, query order lists/details, confirm/delete orders
- 🚚 **Logistics Services** — Freight calculation, logistics time inquiry, logistics tracking
- 🏪 **Store Management** — Store lists, product connections/disconnections, product listings
- 💰 **Payment Functions** — Balance inquiry, order payment, payment link generation
- 🛡️ **Dispute Handling** — Initiate/query/confirm/cancel disputes
- 🔐 **Login Authentication** — UI login, credential verification, session management
## Tech Stack
- **Runtime:** Node.js >= 20.0.0
- **Protocol:** MCP SDK (`@modelcontextprotocol/sdk`)
- **Transport:** stdio (local) / StreamableHTTP (remote)
- **Build:** esbuild
- **Test:** vitest
## Quick Start
### Method 1: VS Code (GitHub Copilot) — Recommended
**Step 1: Get Source Code and Build**
```bash
git clone https://github.com/CJ-dropshipping/api-mcp.git
cd api-mcp
npm install
npm run build
```
Record the project's **absolute path** after building:
```bash
# macOS / Linux
pwd
# Windows (PowerShell)
(Get-Location).Path
```
**Step 2: Configure VS Code MCP**
Create `.vscode/mcp.json` in any workspace root directory, replacing `<absolute path>` with the path obtained in the previous step:
```json
{
"servers": {
"cj-dropshipping": {
"type": "stdio",
"command": "node",
"args": ["<absolute path>/dist/mcp-server/index.cjs"]
}
}
}
```
macOS example:
```json
{
"servers": {
"cj-dropshipping": {
"type": "stdio",
"command": "node",
"args": ["/Users/yourname/api-mcp/dist/mcp-server/index.cjs"]
}
}
}
```
> **Tip**: You can also configure optional environment variables to customize behavior, such as enabling log files:
> ```json
> "env": { "CJ_LOG_LEVEL": "info", "CJ_LOG_FILE": "true" }
> ```
**Step 3: First Login**
1. Open GitHub Copilot Chat in VS Code, switch to **Agent mode**
2. Send a command to Copilot: `Please help me log in to CJ` (or directly use the `show_login_form` tool)
3. Copilot will pop up the CJ login page, enter CJ account password to complete login
4. After successful login, the Session will automatically persist to the local `.cj-token` file, no need to re-login every time
You can use all CJ tools (product search, order management, logistics inquiry, etc.) through natural language after logging in.
### Method 2: ChatGPT (Remote HTTP Mode)
1. Get CJ API Key → Get Access Token
2. Create an MCP application in ChatGPT settings, fill in URL: `https://developers.cjdropshipping.cn/mcp/YOUR_ACCESS_TOKEN`
See [Complete Access Document](https://developers.cjdropshipping.com/en/api/api2/mcp.html) for details.
## Environment Variables
| Variable Name | Default Value | Description |
| --- | --- | --- |
| `CJ_ENV` | `production` | Environment: `production` (production, default), `test` (CJ internal test, only CJ employees can use) |
| `CJ_TRANSPORT` | `stdio` | Transport: `stdio`, `http`, `https` |
| `CJ_HTTP_PORT` | `3009` | HTTP mode listening port |
| `CJ_LOG_LEVEL` | `info` | Log level: `debug`, `info`, `warn`, `error` |
| `CJ_LOG_FILE` | `false` | Output log to file |
| `CJ_LANGUAGE` | `en` | Default language |
| `CJ_CURRENCY` | `USD` | Default currency |
## Local Development
```bash
# Install dependencies
npm install
# Development mode (stdio)
npm run dev
# Build
npm run build
# Run in HTTP mode (test environment)
npm run start:http
# Run in HTTP mode (production environment)
npm run start:production
# Run tests
npm test
```
## Project Structure
```
src/
├── mcp-server/ # MCP server entry
│ └── index.ts # Main entry, register tools and transport layer
├── tools/ # MCP tool implementation
├── services/ # API service layer
├── auth/ # Login authentication module
└── utils/ # General utility functions
tests/ # Test files
docs/ # Documents
logs/ # Running logs (generated when CJ_LOG_FILE=true)
```
## Debugging
### View Logs
Set `CJ_LOG_FILE=true`, log files will be output to `logs/mcp-YYYY-MM-DD.log`.
In VS Code, you can view the corresponding MCP Server's stderr output through the **Output panel**.
### HTTP Debugging
```bash
# Use debugging script
npm run debug:http
# Debugging with logs
npm run debug:http:log
```
### Clear Local Token
```bash
npm run clear-token
```
## Related Documents
- [MCP Integration Guide (English)](https://developers.cjdropshipping.com/en/api/api2/mcp.html)
- [CJ API Documentation](https://developers.cjdropshipping.com/)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
