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

> Explore the xiaohongshu-mcp directory structure. Understand the Go SDK, browser automation, API server, and deployment assets in this comprehensive guide. Optimize your MCP server setup.

- Repository: [zy/xiaohongshu-mcp](https://github.com/xpzouying/xiaohongshu-mcp)
- Tags: tutorial
- Published: 2026-03-09

---

**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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go)** – Configures the HTTP server instance, including port binding, TLS setup, and graceful shutdown handling.
- **[`app_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/app_server.go)** – Optional ancillary server for additional services or health checks.

### Request Handling and Routing

- **[`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go)** – Defines API route definitions and URL patterns for endpoints like `/api/v1/publish` and `/api/v1/feed`.
- **[`mcp_handlers.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_handlers.go)** – Registers HTTP handler functions that process incoming requests and delegate to the service layer.
- **[`middleware.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/middleware.go)** – Implements cross-cutting concerns including request logging, panic recovery, authentication, and request ID generation.
- **[`service.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/login.go)** – Implements the login flow using browser automation to extract session cookies and tokens.
- **[`publish.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/publish.go)** – Handles video and photo publishing logic, including metadata composition.
- **[`publish_video.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/publish_video.go)** – Specific implementation for video file uploads and processing.
- **[`feeds.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/feeds.go)** – Feed retrieval and parsing for user timelines and recommendations.

### Browser Automation (`browser/`)

- **[`browser.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/pipeline.py)** – Python helper script that orchestrates the full publishing pipeline from image download to final post submission.
- **[`cdp_publish.py`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/API.md)** – Official API reference documentation for the server endpoints.
- **[`Windows.md`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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

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

```

This invokes [`main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main.go), which calls the server bootstrap logic in [`mcp_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go) and begins listening on port 8080. All registered routes in [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go) become available at this point.

### Publishing Content via the SDK

```go
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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish.go) and [`xiaohongshu/publish_video.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/xiaohongshu/publish_video.go) to handle the complete publishing workflow.

### Fetching Feeds via HTTP API

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

```

The request routes through [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go), processes through [`middleware.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/middleware.go) for authentication, and delegates to [`xiaohongshu/feeds.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/main.go), [`mcp_server.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go), [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go), [`middleware.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/login.go) for authentication flows, [`publish.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/publish.go) and [`publish_video.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/publish_video.go) for content publishing, and [`feeds.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_server.go) handles the server bootstrap including port binding and TLS configuration; [`routes.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/routes.go) defines the API endpoint mappings; [`mcp_handlers.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/mcp_handlers.go) registers the HTTP handler functions; and [`middleware.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/middleware.go) implements cross-cutting concerns like logging, panic recovery, and authentication. The entry point [`main.go`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/pipeline.py) for orchestrating publishing workflows and [`cdp_publish.py`](https://github.com/xpzouying/xiaohongshu-mcp/blob/main/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.