Shopee MCP Server for Hermes Agent

Dự án này là một MCP (Model Context Protocol) Server viết bằng Python, cung cấp bộ công cụ kết nối trực tiếp với Shopee Open Platform API (Shopee Partner API). Nó cho phép các AI Agent (như Hermes Agent, Claude Desktop, Antigravity, v.v.) tự động hóa quy trình đăng sản phẩm lên Shopee một cách chính thống, an toàn, ổn định và không lo ngại vấn đề bị khóa tài khoản do quét bot trình duyệt (anti-bot).

🚀 Các Tính Năng Hỗ Trợ

• OAuth2 Flow: Quản lý đăng nhập, sinh URL ủy quyền và tự động lưu/refresh tokens.

• Đăng Sản Phẩm (Add Product): Đăng sản phẩm mới với đầy đủ mô tả, giá, tồn kho, kích thước đóng gói và thông tin vận chuyển.

• Quản Lý Hình Ảnh (Upload Image): Tải ảnh trực tiếp từ máy cục bộ hoặc tải từ các đường link URL internet lên Shopee CDN để lấy image_id.

• Tra Cứu Danh Mục & Thuộc Tính: Lấy cây danh mục Shopee (Categories) và các thuộc tính bắt buộc (Attributes) của ngành hàng để đảm bảo đăng sản phẩm chính xác.

• Chế Độ Giả Lập (Mock Mode): Cho phép kiểm thử toàn bộ tính năng và luồng chạy của Agent mà không cần tài khoản Shopee thật.

Related MCP server: Agentic Shopping MCP

🛠️ Yêu Cầu Hệ Thống & Cài Đặt

1. Cài đặt Python: Yêu cầu Python từ 3.10 trở lên.

2. Cài đặt Thư viện: Mở Terminal tại thư mục dự án và chạy câu lệnh sau để cài đặt các thư viện cần thiết:

   pip install -r requirements.txt

⚙️ Cấu Hình Hệ Thống

Tạo file .env tại thư mục gốc của dự án (mặc định đã được tạo sẵn mẫu) và điền các thông tin sau:

# Lấy các thông tin này từ Shopee Developer Console (https://open.shopee.com)
PARTNER_ID=123456
PARTNER_KEY=abcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890
SHOP_ID=987654321

# Dùng API Sandbox để thử nghiệm hoặc API Production để chạy thật
SHOPEE_API_URL=https://partner.test-stable.shopeemobile.com
REDIRECT_URL=https://localhost/callback

# Đặt MOCK_MODE=True để chạy giả lập không cần API key thật
MOCK_MODE=True

# Đường dẫn file tự động lưu token
TOKEN_FILE_PATH=tokens.json

🔗 Tích Hợp Vào Hermes Agent

Để Hermes Agent có thể nhận diện và sử dụng các công cụ này, bạn hãy thêm cấu hình MCP Server vào file cấu hình của Hermes Agent (ví dụ: config.json hoặc thông qua giao diện ứng dụng Hermes Desktop):

{
  "mcpServers": {
    "shopee-mcp": {
      "command": "python",
      "args": [
        "C:/Users/datdt/.gemini/antigravity/scratch/shopee-mcp-server/src/server.py"
      ],
      "env": {
        "ENV_FILE_PATH": "C:/Users/datdt/.gemini/antigravity/scratch/shopee-mcp-server/.env"
      }
    }
  }
}

Lưu ý: Thay đổi các đường dẫn trên thành đường dẫn tuyệt đối chính xác trên máy tính của bạn.

🔄 Quy Trình Ủy Quyền Đăng Nhập (OAuth Flow) cho Shop Thật

Khi tắt MOCK_MODE=False, để bắt đầu gọi được API, Agent và bạn cần làm theo các bước sau:

1. Sinh Link Đăng Nhập: Gọi tool shopee_get_auth_url. Bạn sẽ nhận được 1 link dạng: https://partner.shopeemobile.com/api/v2/shop/auth_partner?...

2. Đồng Ý Ủy Quyền: Truy cập đường link này trên trình duyệt, đăng nhập tài khoản bán hàng Shopee của bạn và bấm nút đồng ý cấp quyền.

3. Lấy Code: Sau khi cấp quyền thành công, trình duyệt sẽ chuyển hướng về REDIRECT_URL của bạn (ví dụ: https://localhost/callback?code=AUTH_CODE_NHAN_DUOC&shop_id=987654321). Copy chuỗi mã code này từ thanh địa chỉ trình duyệt.

4. Kích Hoạt Token: Gọi tool shopee_get_tokens với tham số auth_code=AUTH_CODE_NHAN_DUOC. MCP Server sẽ tự động đổi lấy token và lưu vào file tokens.json. Từ đây, các API đăng sản phẩm sẽ hoạt động hoàn toàn tự động mà không cần bạn can thiệp nữa!

🧪 Cách Thử Nghiệm Với Chế Độ Giả Lập (Mock Mode)

Khi MOCK_MODE=True trong file .env:

• Bạn không cần tài khoản Shopee thật, không cần Partner ID/Key thật.

• Khi bạn nhờ Agent đăng sản phẩm, Agent sẽ tự động chạy tuần tự:

  1. Tự tìm category_id (trả về danh mục mock như Thời Trang Nam, Áo Thun Nam...).

  2. Tự lấy thuộc tính ngành hàng (shopee_get_attributes trả về Thương hiệu, Chất liệu...).

  3. Tải hình ảnh lên Shopee CDN (shopee_upload_image trả về ID mock).

  4. Gọi shopee_add_product và trả về item_id giả lập thành công.

• Điều này giúp bạn kiểm thử được độ thông minh của Agent trong việc điền thông tin sản phẩm và gọi API trước khi chạy thực tế trên shop thật.

📊 Công Cụ Chuyển Đổi Notion Sang Excel BigSeller

Dự án hiện tại đã tích hợp sẵn công cụ chuyển đổi thông minh từ Notion sang Excel theo mẫu BigSeller.

1. Sử dụng độc lập bằng Terminal (Dành cho bạn):

Bạn có thể tự chạy script chuyển đổi cục bộ bằng lệnh:

python -m src.notion_to_bigseller

File Excel chạy thử nghiệm sẽ được xuất ra tại thư mục: C:\Users\datdt\.gemini\antigravity\scratch\shopee-mcp-server\output\bigseller_products_mock.xlsx

2. Sử dụng thông qua Hermes Agent:

MCP Server đã cung cấp sẵn công cụ shopee_convert_notion_to_bigseller_excel. Khi Hermes Agent kết nối với server này, bạn chỉ cần yêu cầu:

"Hãy chuyển đổi trang Notion này sang Excel BigSeller giúp tôi: [Link Notion]"

Agent sẽ tự động gọi tool, phân tích nội dung trang Notion công khai, trích xuất tất cả các đường link hình ảnh có trong bài viết và lưu thành một file Excel hoàn hảo. Bạn chỉ cần tải file này lên BigSeller để đồng bộ hóa lên Shopee!