Xhs MCP

🚀 xhs-mcp

xhs-mcp は統一的なコマンドラインインターフェース xhs-mcp を提供し、MCP サーバーのサブコマンドを内蔵しています。これは小红书（xiaohongshu.com）用の Model Context Protocol（MCP）サーバーと CLI ツールで、ログイン、投稿、検索、推薦などの自動化機能をサポートしています（Puppeteer ベース）。

🚀 クイックスタート

Stdio モード（デフォルト）

npx xhs-mcp mcp

# デバッグログ
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp

初回実行時の注意：Puppeteer ブラウザがインストールされていない場合は、まず以下のコマンドを実行してください。

npx xhs-mcp browser    # Chromium を自動的にチェックしてインストールし、実行可能パスを表示します
# または
npx puppeteer browsers install chrome

出力例：

{
  "success": true,
  "message": "Chromium is ready",
  "data": {
    "installed": true,
    "executablePath": "/path/to/chromium"
  }
}

MCP 接続を検証するには：

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx xhs-mcp mcp

HTTP モード

# HTTP サーバーを起動します（デフォルトポート 3000）
npx xhs-mcp mcp --mode http

# ポートを指定する
npx xhs-mcp mcp --mode http --port 8080

# デバッグモード
XHS_ENABLE_LOGGING=true npx xhs-mcp mcp --mode http

HTTP サーバーは以下をサポートしています：

• Streamable HTTP (プロトコルバージョン 2025-03-26) - エンドポイント：/mcp
• SSE (プロトコルバージョン 2024-11-05) - エンドポイント：/sse と /messages
• ヘルスチェック - エンドポイント：/health

詳細なドキュメントはこちらを参照してください：HTTP Transports

✨ 主な機能

• 認証：ログイン、ログアウト、状態確認
• 投稿：画像と動画の投稿
  • 画像投稿：タイトルは20文字以内（40表示単位）、内容は1000文字以内、画像は最大18枚
  • 動画投稿：MP4、MOV、AVI、MKV、WebM、FLV、WMV 形式をサポート
  • ⭐ 新機能：画像 URL の自動ダウンロード（HTTP/HTTPS）をサポート
  • ⭐ 新機能：タイトル幅の正確な検証（CJK 文字は2単位、ASCII 文字は1単位）
  • ローカル画像パスをサポート
  • URL とローカルパスの混合使用をサポート
  • 重複ダウンロードを避けるためのスマートキャッシュ機構
• 発見：推薦、検索、詳細、コメント
• 自動化：Puppeteer ドライバー、ヘッドレスモード、Cookie 管理

📦 インストール

NPM 情報

• パッケージ名: xhs-mcp
• CLI を実行する（推奨）: npx xhs-mcp <subcommand>
• MCP を起動する：npx xhs-mcp mcp [--mode stdio|http] [--port 3000]

📋 利用可能なツール

• xhs_auth_login、xhs_auth_logout、xhs_auth_status
• xhs_discover_feeds、xhs_search_note、xhs_get_note_detail
• xhs_comment_on_note
• xhs_publish_content（統一投稿インターフェース：type、title、content、media_paths、tags）
  • 画像投稿：1 - 18 個の画像ファイルまたは URL
  • 動画投稿：ちょうど 1 個の動画ファイル
  • 混合使用：画像 URL とローカルパスの混合使用をサポート

💻 使用例

コマンドラインでの使用例

# 認証
npx xhs-mcp login --timeout 120
npx xhs-mcp logout
npx xhs-mcp status

# ブラウザ依存関係
npx xhs-mcp browser [--with-deps]  # Chromium をチェックしてインストールし、実行可能パスを表示します

# 発見と検索
npx xhs-mcp feeds [-b /path/to/chromium]
npx xhs-mcp search -k キーワード [-b /path/to/chromium]
npx xhs-mcp note-detail --feed-id <id> --xsec-token <token> [-b /path/to/chromium]

# インタラクション
npx xhs-mcp comment --feed-id <id> --xsec-token <token> -n "Nice!" [-b /path/to/chromium]

# 投稿
# ローカル画像を使用する
npx xhs-mcp publish --type image --title タイトル --content 内容 -m path1.jpg,path2.png --tags a,b [-b /path/to/chromium]

# ⭐ 画像 URL を使用する（自動ダウンロード）
npx xhs-mcp publish --type image --title タイトル --content 内容 -m "https://example.com/img1.jpg,https://example.com/img2.png" --tags a,b

# URL とローカルパスを混合使用する
npx xhs-mcp publish --type image --title タイトル --content 内容 -m "https://example.com/img1.jpg,./local/img2.jpg" --tags a,b

# 動画を投稿する
npx xhs-mcp publish --type video --title 動画タイトル --content 動画説明 -m path/to/video.mp4 --tags a,b [-b /path/to/chromium]

# 利用可能なツールを表示する
npx xhs-mcp tools [--detailed] [--json]

# MCP を起動する
npx xhs-mcp mcp [--mode stdio|http] [--port 3000]

🔧 技術詳細

クライアント接続（Cursor）

Stdio モード

.cursor/mcp.json：

{
  "mcpServers": {
    "xhs-mcp": {
      "command": "npx",
      "args": ["xhs-mcp", "mcp"],
      "env": { "XHS_ENABLE_LOGGING": "true" }
    }
  }
}

HTTP モード

.cursor/mcp.json：

{
  "mcpServers": {
    "xhs-mcp-http": {
      "command": "npx",
      "args": ["xhs-mcp", "mcp", "--mode", "http", "--port", "3000"],
      "env": { "XHS_ENABLE_LOGGING": "true" }
    }
  }
}

または、HTTP クライアントを直接使用して接続する：

{
  "mcpServers": {
    "xhs-mcp-http": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

⚠️ 重要提示

⚠️ 重要提示

• 画像投稿：タイトルは20文字以内、内容は1000文字以内、画像は18枚以内
• 動画投稿：複数の形式をサポートし、ファイルサイズは500MB 以内を推奨
• 同じアカウントで複数のデバイスから同時にウェブログインしないでください
• 投稿頻度を適切にコントロールしてください
• 画像 URL は ./temp_images/ ディレクトリに自動的にダウンロードされます（自動キャッシュ）
• 画像 URL は JPEG、PNG、GIF、WebP、BMP 形式をサポートします

📖 ドキュメント

📚 ドキュメント

• 完全な使用ガイド - 詳細な使用説明とベストプラクティス
• HTTP トランスポートドキュメント - HTTP/SSE モードの設定
• 投稿ガイド - NPM 投稿フロー

🎨 サンプル

• 使用サンプル - 画像と投稿のサンプル
• サンプル画像 - テストに使用できるサンプル画像

🧪 テスト

• テストの実行 - テストの説明と使い方
• すべてのテストを実行する：npm test

🛠️ ビルドの説明

• 単一の本番ビルド構成を統一的に使用します：config/webpack.config.js
• 開発と最適化のバリエーションは削除されています。開発時は以下を直接実行してください：
  • npm run dev（TypeScript CLI を直接実行）
  • npm run build（dist/xhs-mcp.js にパッケージ化）

📄 ライセンス

このプロジェクトは MIT ライセンス の下でライセンスされています。

🙏 謝辞

このプロジェクトは xiaohongshu-mcp をベースに再構築と拡張されています（TypeScript、Puppeteer、MCP 最適化、ログクリーニング、NPM 投稿）。