Does xiaohongshu-mcp Support Video Uploads? A Complete Technical Guide

Yes, xiaohongshu-mcp fully supports video uploads through its /api/publish_video endpoint and MCP tool integration, using browser automation to handle the actual file upload to Xiaohongshu's platform.

The xpzouying/xiaohongshu-mcp repository implements a Model Context Protocol (MCP) server that enables automated publishing to Xiaohongshu (Little Red Book). This guide examines the complete xiaohongshu-mcp video upload implementation, from API handlers to browser automation.

How Video Upload Works in xiaohongshu-mcp

The video upload process follows a three-tier architecture: API handlers receive requests, the service layer validates and orchestrates, and browser automation executes the actual upload.

API Layer (handlers_api.go)

Incoming video publish requests hit the publishVideoHandler in handlers_api.go. This handler accepts HTTP POST requests to /api/publish_video with a JSON payload containing:

• video: Local file path to the video
• title: Post title (with length validation)
• content: Post body text
• tags: Array of topic tags
• schedule_at: Optional ISO-8601 timestamp for delayed publishing
• visibility: Visibility settings ("公开可见", "仅自己可见", etc.)
• products: Optional product keywords for e-commerce integration

// handlers_api.go - publishVideoHandler extracts the request
type PublishVideoRequest struct {
    Title      string   `json:"title"`
    Content    string   `json:"content"`
    Video      string   `json:"video"`
    Tags       []string `json:"tags"`
    ScheduleAt string   `json:"schedule_at"`
    Visibility string   `json:"visibility"`
    Products   []string `json:"products"`
}

Service Layer (service.go)

The XiaohongshuService.PublishVideo method in service.go orchestrates the operation. It validates the video file exists on disk, checks title length constraints, parses the optional schedule time, and constructs a PublishVideoContent struct.

// service.go - PublishVideo validates and triggers browser automation
func (s *XiaohongshuService) PublishVideo(ctx context.Context, req *PublishVideoRequest) (*PublishVideoResponse, error) {
    // Validation: video file existence, title length, ISO-8601 parsing
    content := &PublishVideoContent{
        Title:      req.Title,
        Content:    req.Content,
        Video:      req.Video,
        Tags:       req.Tags,
        ScheduleAt: req.ScheduleAt,
        Visibility: req.Visibility,
        Products:   req.Products,
    }
    // ... browser automation call
}

Browser Automation (publish_video.go)

The actual upload occurs in xiaohongshu/publish_video.go. The publishVideo function creates a fresh Chromium instance via newBrowser, opens a new page, and invokes xiaohongshu.NewPublishVideoAction to navigate to the publishing interface and switch to the "上传视频" (upload video) tab.

Implementation Details

Video Upload Process

The uploadVideo function in xiaohongshu/publish_video.go handles file selection. It locates the file input element using selectors .upload-input or input[type='file'], then calls Playwright's SetFiles method with the local video path provided in the request.

// xiaohongshu/publish_video.go - uploadVideo implementation
func (a *PublishVideoAction) uploadVideo(page playwright.Page, videoPath string) error {
    // Locate file input: .upload-input or input[type='file']
    fileInput := page.Locator(".upload-input")
    if err := fileInput.SetFiles(videoPath); err != nil {
        return fmt.Errorf("failed to set video file: %w", err)
    }
    
    // Wait for processing completion (Publish button becomes clickable)
    publishBtn := page.Locator(".publish-btn")
    if err := publishBtn.WaitFor(playwright.LocatorWaitForOptions{
        State: playwright.WaitForSelectorStateVisible,
    }); err != nil {
        return fmt.Errorf("video processing timeout: %w", err)
    }
    return nil
}

The function waits until the Publish button becomes clickable, which indicates the video has been processed and transcoded by Xiaohongshu's servers.

Form Submission

After successful upload, submitPublishVideo fills the metadata form. It inputs the title, content body, tags, optional schedule time, visibility settings, and product bindings. The function waits again for the publish button to be enabled (accounting for any validation delays) before finally clicking it to submit the post.

// xiaohongshu/publish_video.go - submitPublishVideo
func (a *PublishVideoAction) submitPublishVideo(page playwright.Page, content *PublishVideoContent) error {
    // Fill title, content, tags
    // Handle schedule_at if provided (ISO-8601 format)
    // Set visibility: 公开可见, 仅自己可见, etc.
    // Bind products if specified
    
    // Final click on publish button
    return page.Locator(".publish-btn").Click()
}

On success, the service returns a PublishVideoResponse containing the title, content, video path, and status string. Errors such as missing video files or invalid schedule formats return HTTP 500 with descriptive messages.

Code Examples

cURL Request (API)

Publish a video immediately via the REST API:

curl -X POST http://localhost:8080/api/publish_video \
  -H "Content-Type: application/json" \
  -d '{
        "title": "我的旅行视频",
        "content": "分享一次难忘的旅程",
        "video": "/path/to/video.mp4",
        "tags": ["旅行","风景"],
        "schedule_at": "2026-04-01T10:00:00Z",
        "visibility": "公开可见",
        "products": ["商品A","商品B"]
      }'

Go Client (Direct Service Call)

Integrate video publishing directly in your Go application:

svc := xiaohongshu.NewXiaohongshuService()
req := &xiaohongshu.PublishVideoRequest{
    Title:      "夏日海边",
    Content:    "海浪声和笑声",
    Video:      "/tmp/sea.mp4",
    Tags:       []string{"海边","夏季"},
    ScheduleAt: "",                     // immediate publish
    Visibility: "仅自己可见",
    Products:   []string{},
}
resp, err := svc.PublishVideo(context.Background(), req)
if err != nil {
    log.Fatalf("video publish failed: %v", err)
}
fmt.Printf("publish succeeded: %+v\n", resp)

MCP Tool Usage (JSON-RPC)

Invoke video upload through the Model Context Protocol:

{
  "method": "publish_with_video",
  "params": {
    "title": "创意短片",
    "content": "看看这段创意短视频",
    "video": "/data/short.mp4",
    "tags": ["创意","短片"],
    "schedule_at": "",
    "visibility": "仅互关好友可见",
    "products": []
  }
}

Key Files and Functions

The xiaohongshu-mcp video upload capability is implemented across these source files:

File	Purpose
xiaohongshu/publish_video.go	Core video upload logic including NewPublishVideoAction, uploadVideo, and submitPublishVideo
service.go	Service-level validation, PublishVideo orchestration, and PublishVideoContent struct definitions
mcp_handlers.go	MCP tool endpoint (handlePublishVideo) exposing video publish to AI agents
handlers_api.go	HTTP API handler (publishVideoHandler) for RESTful video publishing
README.md / docs/API.md	Documentation covering video publishing endpoints and parameters

Summary

• xiaohongshu-mcp supports complete video upload workflows via REST API, Go service calls, and MCP tool integration.
• The upload process uses Playwright browser automation to interact with Xiaohongshu's web interface, handling file selection via SetFiles and waiting for server-side transcoding.
• Validation occurs at multiple layers: file existence checks, title length limits, and ISO-8601 schedule parsing in service.go.
• The implementation spans xiaohongshu/publish_video.go for automation, service.go for business logic, and handlers_api.go/mcp_handlers.go for interface exposure.

Frequently Asked Questions

What video formats does xiaohongshu-mcp support?

The project itself does not enforce specific codec restrictions; format support depends on Xiaohongshu's platform requirements. The automation layer in xiaohongshu/publish_video.go passes the file path directly to the browser's file input, allowing the platform's native transcoding to handle format validation.

Can I schedule video posts for future publication?

Yes. The PublishVideoRequest struct accepts an optional schedule_at parameter in ISO-8601 format (e.g., 2026-04-01T10:00:00Z). The XiaohongshuService.PublishVideo method in service.go parses this timestamp and the automation layer selects the scheduled publishing option in the web interface.

How does xiaohongshu-mcp handle video processing delays?

The uploadVideo function in xiaohongshu/publish_video.go implements explicit waits using Playwright's WaitFor methods. After calling SetFiles on the file input, it waits for the Publish button to become visible and clickable, which indicates that Xiaohongshu's servers have finished transcoding and processing the video file.

Is there a difference between the API and MCP methods for video upload?

Both methods ultimately invoke the same XiaohongshuService.PublishVideo function in service.go. The publishVideoHandler in handlers_api.go provides a REST HTTP interface, while handlePublishVideo in mcp_handlers.go exposes the functionality as an MCP tool for AI agent integration. The request payload structure and validation logic remain identical between both interfaces.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}