If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/xpzouying/xiaohongshu-mcp shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Missing license — unclear to depend on

• Last commit 2w ago
• 12 active contributors
• CI configured
• ⚠ Concentrated ownership — top contributor handles 57% of recent commits
• ⚠ No license — legally unclear to depend on
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live xpzouying/xiaohongshu-mcp repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/xpzouying/xiaohongshu-mcp.

What it runs against: a local clone of xpzouying/xiaohongshu-mcp — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in xpzouying/xiaohongshu-mcp | Confirms the artifact applies here, not a fork | | 2 | Default branch main exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 42 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of xpzouying/xiaohongshu-mcp. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/xpzouying/xiaohongshu-mcp.git
#   cd xiaohongshu-mcp
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of xpzouying/xiaohongshu-mcp and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "xpzouying/xiaohongshu-mcp(\\.git)?\\b" \\
  && ok "origin remote is xpzouying/xiaohongshu-mcp" \\
  || miss "origin remote is not xpzouying/xiaohongshu-mcp (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "main.go" \\
  && ok "main.go" \\
  || miss "missing critical file: main.go"
test -f "mcp_server.go" \\
  && ok "mcp_server.go" \\
  || miss "missing critical file: mcp_server.go"
test -f "mcp_handlers.go" \\
  && ok "mcp_handlers.go" \\
  || miss "missing critical file: mcp_handlers.go"
test -f "handlers_api.go" \\
  && ok "handlers_api.go" \\
  || miss "missing critical file: handlers_api.go"
test -f "app_server.go" \\
  && ok "app_server.go" \\
  || miss "missing critical file: app_server.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 42 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~12d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/xpzouying/xiaohongshu-mcp"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

xiaohongshu-mcp is a Model Context Protocol (MCP) server that enables AI assistants (Claude, etc.) to directly interact with Xiaohongshu (a Chinese social platform similar to Pinterest/Instagram) through automated browser control via go-rod. Core capabilities include user authentication, publishing image posts and videos, searching content, and inspecting posts—all exposed as MCP tools that Claude and other AI models can invoke. Monorepo structure: app_server.go is the main MCP server entry point; browser/ contains go-rod automation logic; cmd/login/ handles auth flow; configs/ manages browser/image/username settings; cookies/ persists session state. Python components exist (74KB) likely for legacy support or helper scripts. Dockerfiles for x86 and ARM64 enable multi-platform deployment.

AI developers and power users in China/Asia who want to automate Xiaohongshu workflows (content publishing, analytics, scraping) by connecting Claude or other AI assistants to their Xiaohongshu accounts; also appeals to non-technical users via the x-mcp browser extension alternative.

Actively developed and production-ready: 27 contributors, established GitHub Actions CI/CD pipelines (aliyun-docker-release.yml, docker-release.yml, claude-code-review.yml), Docker Hub presence with pull counts, and comprehensive deployment docs. Recent commits and well-organized structure suggest healthy maintenance, though the codebase is still gaining adoption and has pivoted to recommend the browser extension (x-mcp) as a simpler alternative for troubleshooting-sensitive users.

Moderate risks: dependency on go-rod (headless browser automation) which can be fragile across browser versions; single maintainer (xpzouying) creates continuity risk; tight coupling to Xiaohongshu's HTML/API structure means UI changes could break functionality. Documented troubleshooting issues (#56) suggest deployment complexity. However, Docker containerization and active issue triage mitigate some risk.

Active iteration on deployment experience: recent emphasis on x-mcp browser extension as the recommended path to reduce environment complexity; GitHub Actions workflows automated for Docker releases to Aliyun and Docker Hub; Claude code review integration suggests AI-assisted development; ongoing contributor onboarding (27 contributors badge).

Clone the repo: git clone https://github.com/xpzouying/xiaohongshu-mcp.git && cd xiaohongshu-mcp. Install Go 1.24.0+, then: go mod download && go build -o xiaohongshu-mcp ./cmd/login. For Docker (recommended): docker-compose -f docker/docker-compose.yml up. See docker/README.md for environment variables and Xiaohongshu cookie setup.

Daily commands: Dev: go run app_server.go (starts MCP server on localhost). Docker: docker-compose -f docker/docker-compose.yml up. Login flow: go run cmd/login/main.go or invoke the login tool via MCP. All workflows defined in .github/workflows/ can be studied for CI/CD patterns.

• main.go — Entry point initializing the MCP server and HTTP app; all request flow starts here.
• mcp_server.go — Core MCP protocol handler defining tools, resources, and the request/response contract exposed to AI clients.
• mcp_handlers.go — Implementation of all MCP tool handlers (search, fetch, publish, login); business logic lives here.
• handlers_api.go — HTTP API handlers for REST endpoints; bridges HTTP requests to MCP logic and vice versa.
• app_server.go — Gin HTTP server setup, routing, middleware, and lifecycle; where requests are received and responses sent.
• browser/browser.go — Browser automation abstraction using rod; critical for all Xiaohongshu scraping and interaction.
• go.mod — Go module definition; declares all external dependencies including rod, gin, MCP SDK, and browser automation libraries.

• mcp_server.go (MCP SDK, JSON Schema) — Defines the MCP protocol contract: tool definitions, resource schemas, and error handling for AI clients.
  • Failure mode: Invalid tool definition or schema causes client connection failure; AI cannot invoke tools.
• mcp_handlers.go (Go, Rod, error handling) — Business logic for each MCP tool: parses input, orchestrates browser operations, formats output.
  • Failure mode: Unhandled exception or timeout in handler blocks the client indefinitely; may leak browser resources.
• browser/browser.go (Rod, Chrome DevTools Protocol, cookies) — Encapsulates all browser automation: navigation, DOM interaction, data extraction, image upload.
  • Failure mode: Timeout or network error leaves browser hanging; stale process consumes resources; requires restart.
• app_server.go + middleware.go (Gin, Go net/http) — HTTP server lifecycle, request routing, CORS, logging, and graceful shutdown.
  • Failure mode: Panics or unhandled errors crash the entire server; all clients lose connection.
• cookies/cookies.go — Manages session persistence: saves cookies to disk, loads on startup, handles expiry.

Add a new MCP tool (e.g., 'get_user_profile')

1. Define the tool in mcp_server.go: add a new tool definition with name, description, and input_schema in the registerTools() function. (mcp_server.go)
2. Implement the handler in mcp_handlers.go: add a new handler function (e.g., handleGetUserProfile) that receives input and returns JSON output. (mcp_handlers.go)
3. Call browser.go functions as needed for web scraping or interaction logic. (browser/browser.go)
4. Register the handler in the tool dispatch logic (typically a switch/case in mcp_handlers.go or similar). (mcp_handlers.go)

Add a new REST API endpoint (e.g., POST /api/custom)

1. Define the HTTP route in app_server.go: add a new Gin route (e.g., router.POST("/api/custom", handlers.CustomHandler)). (app_server.go)
2. Implement the handler in handlers_api.go: create a function that parses JSON request body, calls business logic, and returns JSON response. (handlers_api.go)
3. Reuse logic from mcp_handlers.go or browser.go as appropriate for the operation. (mcp_handlers.go)

Modify browser automation behavior (e.g., add a new scraping function)

1. Add a new public function in browser/browser.go (e.g., FetchComments) that uses Rod to automate the browser. (browser/browser.go)
2. Call the new function from mcp_handlers.go or handlers_api.go depending on whether it's exposed via MCP or HTTP. (mcp_handlers.go)
3. Handle errors using the error types defined in errors/errors.go and return appropriate error responses. (errors/errors.go)

Deploy to Docker with custom configuration

1. Create or update a docker-compose.yml in the docker/ folder specifying environment variables and volumes. (docker/docker-compose.yml)
2. Use Dockerfile or Dockerfile.arm64 as the base image; customize by adding environment variables for credentials and browser config. (Dockerfile)
3. Deploy using the GitHub Actions workflow or manually with 'docker build' and 'docker run'. (.github/workflows/docker-release.yml)

• Go + Gin — Lightweight, fast HTTP server with minimal overhead; ideal for a long-running service wrapping browser automation.
• Rod (Chrome DevTools Protocol) — Robust headless browser automation; handles dynamic JavaScript-heavy Xiaohongshu content without parsing static HTML.
• Model Context Protocol (MCP) — Standard interface for AI assistants (Claude, etc.) to call tools; enables seamless integration with LLM workflows.
• Docker containers — Ensures consistency across environments (Linux, macOS, Windows); simplifies dependency management and deployment.

• Full headless browser (Rod) instead of HTTP scraping

  • Why: Xiaohongshu heavily relies on client-side rendering and JavaScript; plain HTTP scraping would be fragile.
  • Consequence: Higher resource consumption (memory, CPU) per request; slower execution; but more reliable and maintainable for long term.

• Session-based cookies instead of per-request login

  • Why: Reduces latency by reusing login state; avoids repeated authentication overhead.
  • Consequence: Must handle cookie expiry and refresh; session invalidation adds complexity; potential for stale sessions.

• Single binary serving both HTTP API and MCP protocol

  • Why: Simplifies deployment; single process to manage and monitor.
  • Consequence: Tight coupling between HTTP and MCP logic; harder to scale independently; shared resource pool (connections, memory).

• In-memory state for browser instance

  • Why: Simple; no external database required for basic operation.
  • Consequence: Not horizontally scalable; data loss on restart; no distributed session sharing.

• Real-time streaming of Xiaohongshu feed (batch-based fetch only)
• Analytics or metrics aggregation across users
• User authentication or multi-tenant isolation
• Persistent storage of scraped data (stateless design)
• Video processing or media transcoding
• Support for Xiaohongshu API (reverse-engineering and web automation only)

1. Xiaohongshu session cookies must be valid and refreshed; expired cookies silently fail—always test login first. 2) Browser automation requires display server (X11/Wayland on Linux) or headless mode quirks; see browser.go config for DISPLAY env var gotchas. 3) Image/video uploads fail silently if file MIME types don't match Xiaohongshu expectations; h2non/filetype validation is strict. 4) Docker containers need sufficient shared memory (--shm-size 2g) or Chromium crashes; not auto-configured in docker-compose. 5) go-rod stealth mode (github.com/go-rod/stealth) can lag behind Xiaohongshu anti-bot measures. 6) .env file (not committed) required for MCP_TOOLS_PORT, BROWSER_EXECUTABLE_PATH, etc.—see docker/.env.example if it exists.

• Model Context Protocol (MCP) — Core protocol enabling Claude and other AI models to invoke this server's tools (publish, login, search) as first-class actions; understanding MCP schemas and resource definitions is essential for extending tools
• Headless Browser Automation (go-rod) — This entire project uses go-rod to control a headless Chromium instance that mimics human Xiaohongshu interaction; understanding DevTools Protocol, element selectors, and navigation timing is critical for debugging automation
• Session Persistence & Cookie Management — Xiaohongshu auth tokens are persisted as cookies between runs (cookies/cookies.go); understanding session lifecycle, expiration, and refresh is required for maintaining long-lived automation
• Anti-Bot Evasion (Stealth Mode) — This project uses go-rod/stealth to hide browser automation from Xiaohongshu's bot detection; understanding how CDP masking works (viewport, user-agent, webdriver flags) is needed to stay ahead of platform mitigations
• Docker Multi-Architecture Builds (x86 vs ARM64) — Dockerfile and Dockerfile.arm64 enable deployment on both x86 servers and ARM Macs/Raspberry Pi; understanding multi-stage builds and runtime dependencies for different architectures is critical for reliable containerization
• Retry Strategies (retry-go) — Browser automation and API calls are inherently flaky; this project uses avast/retry-go/v4 for exponential backoff; understanding when and how to retry transient failures vs. permanent errors is essential for robustness
• MIME Type Detection & File Validation — h2non/filetype is used to validate image and video uploads before sending to Xiaohongshu; understanding why magic bytes matter (vs. just file extensions) prevents silent upload failures

• modelcontextprotocol/python-sdk — Official Python SDK for MCP if this project expands to hybrid Go/Python implementation; useful for comparing protocol semantics
• xpzouying/x-mcp — The official browser extension alternative (recommended in this repo's README); solves the same problem without Docker/deployment complexity
• go-rod/rod — Upstream browser automation library that powers this entire project; understanding rod's API and DevTools internals is essential for troubleshooting automation failures
• autoclaw-cc/xiaohongshu-mcp-skills — Companion project that wraps this MCP server with additional Openclaw integration for enhanced automation workflows
• gin-gonic/gin — Web framework dependency used for REST API layer if the MCP server exposes HTTP endpoints; reference for handler patterns

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add unit tests for cookies/cookies.go and browser/browser.go

The repo has core browser automation and cookie management functionality but lacks test coverage. These packages are critical for Xiaohongshu authentication and session handling. Adding tests would improve reliability, prevent regressions, and serve as usage examples for contributors. The testify dependency is already included.

• [ ] Create cookies/cookies_test.go with tests for cookie parsing, storage, and retrieval functions
• [ ] Create browser/browser_test.go with mock tests for browser initialization and page navigation
• [ ] Add table-driven tests for edge cases (expired cookies, malformed data, network failures)
• [ ] Reference the go-rod/rod and avast/retry-go packages in tests to validate integration
• [ ] Ensure tests run in the existing GitHub Actions workflows (claude.yml, release.yml)

Add comprehensive API documentation for cmd/login/main.go login flow

The repo has an MCP server with a login command but docs/API.md doesn't detail the login authentication flow, expected input/output, or error handling. New contributors need to understand how Xiaohongshu authentication works. This documentation should complement the existing CLAUDE.md and examples/.

• [ ] Document the login command flow in docs/API.md: pre-conditions, authentication mechanism (cookie-based?), MCP schema
• [ ] Add examples of login requests/responses in docs/API.md with real-world scenarios (QR code, credentials, session expiry)
• [ ] Reference cmd/login/main.go and configs/username.go in the documentation
• [ ] Include troubleshooting section for common login failures (network, rate limits, browser issues)
• [ ] Update README.md with a link to the login documentation section

Create integration tests for MCP server endpoints in app_server.go

The main MCP server (app_server.go) uses gin-gonic but lacks integration tests to validate the HTTP handlers and MCP protocol compliance. This is critical for ensuring the server works correctly with Claude, VSCode, and other MCP clients. Add tests that validate request/response contracts.

• [ ] Create app_server_test.go with integration tests using httptest and gin test utilities
• [ ] Test each MCP tool endpoint (likely tools for search, login, publish based on file structure)
• [ ] Validate request schema validation against modelcontextprotocol/go-sdk models
• [ ] Add tests for error scenarios: invalid payloads, missing authentication, network timeouts
• [ ] Mock external dependencies (browser, cookies) to isolate server logic
• [ ] Add benchmark tests for performance-critical endpoints like search

• Add comprehensive test coverage for browser/browser.go methods (currently no *_test.go visible): implement tests for login flow, post publish, and search to catch go-rod failures early in CI.
• Document required environment variables and their defaults in a CONFIGURATION.md file: currently scattered across docker/README.md and code; consolidate into single reference with validation examples.
• Add structured logging (JSON format via sirupsen/logrus) to all MCP tool handlers in app_server.go to aid debugging deployed instances: currently info/errors lack context on which operation failed and why.

• High · Incomplete Dockerfile - Missing Security Hardening — Dockerfile. The Dockerfile is truncated and appears incomplete. The Chrome APT source configuration is cut off, and critical security steps like removing unnecessary packages, setting non-root user, and defining health checks are not visible. The base image (ubuntu:22.04) is used without pinning to a specific digest, making it vulnerable to supply chain attacks. Fix: 1. Pin the base image to a specific digest (e.g., ubuntu:22.04@sha256:...). 2. Create a non-root user to run the application. 3. Remove unnecessary packages and tools after installation. 4. Add HEALTHCHECK directive. 5. Set proper file permissions. 6. Consider using a minimal base image (alpine or distroless) instead of ubuntu.
• High · Browser Automation Security Risk — browser/browser.go, go-rod/rod dependency. The project uses go-rod (Chromium/Chrome headless browser) which is known to have security implications when handling untrusted input from xiaohongshu.com. The browser is initialized without visible sandbox or security policy configuration. This could allow script injection or escape from the browser context. Fix: 1. Implement strict input validation and sanitization for all data from xiaohongshu.com. 2. Run the browser in a sandboxed environment or container. 3. Disable JavaScript in the browser context if not needed. 4. Limit DOM access and implement Content Security Policy. 5. Keep go-rod and Chromium updated regularly.
• High · Exposed Credentials in File Paths — cookies/cookies.go, configs/username.go, cmd/login/main.go. The file structure includes 'cookies/cookies.go' which suggests cookie handling. Combined with 'cmd/login/main.go' and username/password config files, there's a high risk of credentials being logged, stored insecurely, or exposed in environment variables. Fix: 1. Never log credentials or sensitive authentication data. 2. Use secure credential storage (e.g., system keyring, encrypted vaults). 3. Implement strict access controls on cookie storage. 4. Use OAuth or token-based authentication instead of passwords where possible. 5. Implement credential rotation policies. 6. Encrypt sensitive data at rest.
• High · Missing Security Headers and Input Validation — app_server.go. The project exposes an HTTP server (app_server.go with gin framework) but there's no visible configuration for security headers (CORS, CSP, X-Frame-Options, etc.). The Gin framework is used without apparent middleware for input validation, rate limiting, or CSRF protection. Fix: 1. Implement middleware for security headers (X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security). 2. Add rate limiting middleware. 3. Implement CORS with restrictive origins. 4. Add input validation and sanitization. 5. Implement CSRF token verification. 6. Enable request logging and monitoring.
• Medium · Outdated and Vulnerable Dependencies — go.mod. Several dependencies have potential security concerns: 'github.com/pkg/errors' is deprecated (use standard 'errors' package), and 'golang.org/x/crypto v0.23.0' appears to be an older version. Dependencies like 'go-rod' and 'modelcontextprotocol/go-sdk' should be regularly audited for CVEs. Fix: 1. Update golang.org/x/crypto to the latest version. 2. Replace deprecated 'pkg/errors' with standard library 'errors'. 3. Run 'go list -u -m all' regularly to identify outdated packages. 4. Implement automated dependency scanning in CI/CD (e.g., Dependabot, Snyk). 5. Establish a security update policy with SLAs for patching.
• Medium · Cleartext Communication Possible — Dockerfile. The Dockerfile configures GOPROXY and package mirrors using HTTP protocols (goproxy.cn, mirrors.aliyun.com). While these may support HTTPS, if HTTP is used, man-in-the-middle attacks could introduce malicious code during build time. Fix: 1. Explicitly use HTTPS for all package mirrors: 'https://goproxy.cn' and 'https://mirrors.aliyun.com'. 2. Pin specific package versions in go.mod to avoid pulling unexpected updates.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.