Directory Structure of xiaohongshu-mcp: Complete Guide to the Go-Based MCP Server

The xiaohongshu-mcp repository organizes its Go-based codebase into logical top-level directories separating core SDK code, browser automation, API server components, configuration, Python automation scripts, and deployment assets.

The xiaohongshu-mcp project is a Go-based multi-component system that bundles a command-line client, HTTP API server, and browser automation tools for interacting with Xiaohongshu (Little Red Book). Understanding the directory structure of xiaohongshu-mcp is essential for developers looking to extend the platform, debug issues, or deploy the MCP server in production environments.

Top-Level Directory Layout

The repository root contains eight primary logical groupings that separate concerns from core application code to deployment configuration:

.
├─ .github/                ← GitHub Actions workflows, CODEOWNERS, FUNDING
├─ assets/                 ← Screenshots, GIFs, videos used in documentation
├─ browser/                ← Browser automation (Chromium via go-rod)
├─ configs/                ← Runtime configuration structs
├─ cookies/                ← Cookie handling utilities
├─ deploy/                 ← Deployment configurations
│   └─ macos/              ← launchd plist, fish wrapper
├─ docs/                   ← User guides and API specifications
├─ examples/               ← Sample workflows
│   └─ n8n/                ← n8n automation JSON
├─ skills/                 ← Automation skill implementations
│   └─ post-to-xhs/
│       └─ scripts/        ← Python helper scripts
├─ xiaohongshu/            ← Core SDK: API calls, models, helpers
├─ pkg/                    ← Shared utility packages
│   └─ xhsutil/            ← Title handling utilities
├─ .vscode/                ← VSCode configuration
├─ .cursor/                ← Cursor AI configuration
└─ [Root-level Go files]   ← Application entry points and server setup

Core Application Layer

The root directory contains the primary Go source files that bootstrap the MCP server and handle HTTP request routing. These files implement the command-line interface and HTTP API surface.

Entry Point and Server Bootstrap

• main.go – Application entry point that parses command-line flags and determines whether to run as a CLI tool or start the HTTP API server.
• mcp_server.go – Configures the HTTP server instance, including port binding, TLS setup, and graceful shutdown handling.
• app_server.go – Optional ancillary server for additional services or health checks.

Request Handling and Routing

• routes.go – Defines API route definitions and URL patterns for endpoints like /api/v1/publish and /api/v1/feed.
• mcp_handlers.go – Registers HTTP handler functions that process incoming requests and delegate to the service layer.
• middleware.go – Implements cross-cutting concerns including request logging, panic recovery, authentication, and request ID generation.
• service.go – Core service orchestration layer that coordinates between HTTP handlers and the Xiaohongshu SDK.

SDK and Browser Automation

The xiaohongshu/ directory contains the core SDK that mirrors the official Xiaohongshu API, while browser/ handles Chrome automation for authentication flows.

Xiaohongshu SDK (xiaohongshu/)

This package implements the business logic for interacting with Xiaohongshu's private API endpoints:

• login.go – Implements the login flow using browser automation to extract session cookies and tokens.
• publish.go – Handles video and photo publishing logic, including metadata composition.
• publish_video.go – Specific implementation for video file uploads and processing.
• feeds.go – Feed retrieval and parsing for user timelines and recommendations.

Browser Automation (browser/)

• browser.go – Thin wrapper around github.com/go-rod/rod that manages Chrome DevTools Protocol (CDP) connections, page navigation, and element interaction for authentication flows.

Configuration and Utilities

Supporting infrastructure for runtime configuration and shared utilities.

Configuration Management

• configs/ – Contains Go structs that define runtime configuration options, including username credentials, image processing parameters, and browser automation flags. Supports environment variables and JSON configuration files.
• cookies/ – Cookie handling utilities for persisting and loading session state between browser automation and API requests.

Shared Packages

• pkg/xhsutil/ – Utility package containing helper functions for title handling, text processing, and other shared operations used across the SDK and server layers.

Automation and Examples

Pre-built automation scripts and workflow examples for common use cases.

Skill Scripts (skills/post-to-xhs/scripts/)

• pipeline.py – Python helper script that orchestrates the full publishing pipeline from image download to final post submission.
• cdp_publish.py – Chrome DevTools Protocol publishing script for advanced automation scenarios.
• Additional utilities for image processing and metadata generation.

Workflow Examples (examples/n8n/)

• 自动发布笔记到小红书.json – n8n workflow JSON file that demonstrates automated note publishing to Xiaohongshu, including authentication, content preparation, and publishing steps.

Documentation (docs/)

• API.md – Official API reference documentation for the server endpoints.
• Windows.md – Setup guide for Windows environments.

Deployment Assets

Configuration files and scripts for deploying the MCP server in production environments.

• deploy/macos/ – macOS-specific deployment files including launchd plist configurations for background service management and fish shell wrapper scripts.
• Dockerfile – Standard container image definition for x86_64 deployments.
• Dockerfile.arm64 – ARM64-specific container image for Apple Silicon and ARM servers.

Code Examples

Starting the MCP Server

// Terminal command to start the server
$ go run ./main.go server --port 8080

This invokes main.go, which calls the server bootstrap logic in mcp_server.go and begins listening on port 8080. All registered routes in routes.go become available at this point.

Publishing Content via the SDK

package main

import (
    "log"
    "github.com/xpzouying/xiaohongshu-mcp/xiaohongshu"
)

func main() {
    // Initialize client with existing session
    client := xiaohongshu.NewClient()
    
    videoPath := "/path/to/video.mp4"
    title := "我的第一条小红书视频"
    
    // Publish with optional metadata
    resp, err := client.PublishVideo(videoPath, title, nil)
    if err != nil {
        log.Fatalf("publish failed: %v", err)
    }
    log.Printf("published successfully, post ID: %s", resp.PostID)
}

This example utilizes xiaohongshu/publish.go and xiaohongshu/publish_video.go to handle the complete publishing workflow.

Fetching Feeds via HTTP API

curl -X GET "http://localhost:8080/api/v1/feed?user_id=123456" \
     -H "Authorization: Bearer <your-token>"

The request routes through routes.go, processes through middleware.go for authentication, and delegates to xiaohongshu/feeds.go via the service layer.

Implementing n8n Automation

Import the workflow file located at examples/n8n/自动发布笔记到小红书.json into your n8n instance. The workflow orchestrates:

1. Trigger – Manual or scheduled execution
2. Authentication – Calls /api/v1/login to establish session
3. Content Processing – Executes Python scripts from skills/post-to-xhs/scripts/ for media handling
4. Publishing – Submits final payload to /api/v1/publish

Summary

• The directory structure of xiaohongshu-mcp separates concerns across eight top-level categories: core application code, SDK implementation, browser automation, configuration, utilities, automation scripts, documentation, and deployment assets.
• Root-level Go files (main.go, mcp_server.go, routes.go, middleware.go) handle application bootstrap, HTTP server configuration, and request routing.
• The xiaohongshu/ directory contains the core SDK implementing login, publishing, and feed retrieval functionality that mirrors the official Xiaohongshu API.
• Browser automation resides in browser/ using the go-rod library for Chrome DevTools Protocol interactions during authentication flows.
• Automation capabilities extend through Python scripts in skills/post-to-xhs/scripts/ and n8n workflow examples in examples/n8n/.

Frequently Asked Questions

What is the purpose of the xiaohongshu/ directory in the repository?

The xiaohongshu/ directory serves as the core SDK that mirrors the official Xiaohongshu (Little Red Book) API. It contains Go source files implementing critical functionality including login.go for authentication flows, publish.go and publish_video.go for content publishing, and feeds.go for retrieving user feeds and recommendations.

How does the browser automation work in xiaohongshu-mcp?

Browser automation is handled by the browser/ directory, specifically browser/browser.go, which provides a thin wrapper around the github.com/go-rod/rod library. This implementation manages Chrome DevTools Protocol (CDP) connections to automate Chromium-based browser actions, primarily used during the login flow in xiaohongshu/login.go to extract session cookies and authentication tokens.

What files control the HTTP API server configuration?

The HTTP API server is orchestrated by several root-level Go files: mcp_server.go handles the server bootstrap including port binding and TLS configuration; routes.go defines the API endpoint mappings; mcp_handlers.go registers the HTTP handler functions; and middleware.go implements cross-cutting concerns like logging, panic recovery, and authentication. The entry point main.go determines whether to run as a CLI tool or start the server based on command-line flags.

Where are the automation scripts and workflow examples located?

Automation resources are distributed across two main directories: skills/post-to-xhs/scripts/ contains Python helper scripts including pipeline.py for orchestrating publishing workflows and cdp_publish.py for Chrome DevTools Protocol publishing; examples/n8n/ contains the n8n workflow JSON file 自动发布笔记到小红书.json, which demonstrates automated note publishing through a visual workflow automation platform.

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