Xiaohongshu MCP Python

🚀 小红书MCP Python版

🐍 小红书MCPのPythonバージョン - Model Context Protocolに基づく小红书の自動コンテンツ投稿ツール

🚀 クイックスタート

xiaohongshu-mcp-pythonは、Pythonで開発された小红书のコンテンツ投稿自動化ツールです。このツールは、Model Context Protocol (MCP) を介してAIクライアントに小红书の操作機能を提供します。

📋 環境要件

• Python 3.8以上
• uvパッケージマネージャー
• サポートされるオペレーティングシステム：Linux、macOS、Windows

🔧 インストール手順

1. プロジェクトをクローンする

   git clone https://github.com/your-username/xiaohongshu-mcp-python.git
   cd xiaohongshu-mcp-python
   

2. uvパッケージマネージャーをインストールする

   # macOS/Linux
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

3. 国内ミラーソースを設定する（オプション）

   export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple
   

4. 依存関係をインストールする

   uv sync
   

5. Playwrightブラウザをインストールする

   uv run playwright install chromium
   

⚙️ 環境設定

このプロジェクトは、開発環境と本番環境の2つのモードをサポートしており、環境変数または .env ファイルを使用して設定できます。

📋 環境モードの説明

🔧 設定方法

方法1：.env ファイルを使用する（推奨）

1. サンプル設定ファイルをコピーする：

   cp .env.example .env
   

2. .env ファイルを編集する：

   # ============ 環境設定 ============
   # 選択可能な値: development, production
   # development: 開発環境（ヘッド付きブラウザ、DEBUGログ）
   # production: 本番環境（ヘッドレスブラウザ、INFOログ）
   ENV=development
   
   # ============ ブラウザ設定 ============
   # ヘッドレスブラウザモードを使用するかどうか
   # true: ヘッドレスモード（ブラウザウィンドウを表示しない）
   # false: ヘッド付きモード（ブラウザウィンドウを表示する）
   # 設定されていない場合、ENVに応じて自動的に決定されます（開発環境=ヘッド付き、本番環境=ヘッドレス）
   # BROWSER_HEADLESS=false
   
   # ============ ログ設定 ============
   # ログレベル: DEBUG, INFO, WARNING, ERROR, CRITICAL
   # 開発環境のデフォルト: DEBUG
   # 本番環境のデフォルト: INFO
   # LOG_LEVEL=DEBUG
   
   # ログファイルのパス（オプション、設定するとログがファイルに書き込まれます）
   # LOG_FILE=logs/xiaohongshu-mcp.log
   
   # ============ サーバー設定 ============
   # サーバーのリッスンアドレス
   SERVER_HOST=127.0.0.1
   
   # サーバーのポート
   SERVER_PORT=8000
   
   # ============ ユーザー設定 ============
   # デフォルトのユーザー名
   GLOBAL_USER=luyike
   
   # ============ タイムアウト設定 ============
   # ページロードのタイムアウト時間（ミリ秒）
   PAGE_LOAD_TIMEOUT=60000
   
   # 要素の待機タイムアウト時間（ミリ秒）
   ELEMENT_TIMEOUT=30000
   

方法2：環境変数を使用する

# 開発環境
export ENV=development
export BROWSER_HEADLESS=false
export LOG_LEVEL=DEBUG

# 本番環境
export ENV=production
export BROWSER_HEADLESS=true
export LOG_LEVEL=INFO

方法3：コマンドライン引数を使用する（最も優先度が高い）

# 開発モードで起動（デフォルト）
uv run python -m xiaohongshu_mcp_python.main

# 本番モードで起動
uv run python -m xiaohongshu_mcp_python.main --env production

# 開発モードでヘッドレスブラウザを使用する
uv run python -m xiaohongshu_mcp_python.main --env development --headless

# 本番モードでヘッド付きブラウザを使用する（デバッグ用）
uv run python -m xiaohongshu_mcp_python.main --env production --no-headless

# カスタムログレベルを指定する
uv run python -m xiaohongshu_mcp_python.main --env development --log-level DEBUG

# ログファイルを指定する
uv run python -m xiaohongshu_mcp_python.main --log-file logs/app.log

🎛️ 利用可能な設定項目

📝 ログシステム

ログシステムは以下の特性をサポートしています：

• コンソール出力：デフォルトでコンソールに出力され、カラー表示をサポートしています。
• ファイル出力：LOG_FILE を設定することで、同時にファイルに書き込むことができます。
• ログローテーション：ファイルログは自動的にローテーションされます（10MB）。
• ログ保持：直近7日間のログが保持されます。
• 自動圧縮：古いログは自動的にzip形式で圧縮されます。

ログフォーマット：

{time:YYYY-MM-DD HH:mm:ss} | {level:<8} | {name}:{function}:{line} - {message}

🎯 サービスの起動

# 開発モードで起動（デフォルト）
uv run python -m xiaohongshu_mcp_python.main

# 本番モードで起動
uv run python -m xiaohongshu_mcp_python.main --env production

# ヘルプ情報を表示する
uv run python -m xiaohongshu_mcp_python.main --help

起動後、サービスは http://localhost:8000（または設定されたポート）で起動します。 起動時には環境設定情報が表示されます：

============================================================
小红书MCPサーバーが起動しました
実行環境: 開発環境 (development)
ブラウザモード: ヘッド付きモード
ログレベル: DEBUG
サーバーアドレス: http://127.0.0.1:8000
デフォルトユーザー: luyike
============================================================

✨ 主な機能

🚀 現代的なPythonアーキテクチャ

Python 3.8+ と非同期プログラミングに基づいています。

🎯 MCPプロトコルのサポート

Model Context Protocol 仕様を完全に実装しています。

🌐 Playwrightドライバー

Seleniumの代わりにPlaywrightを使用しており、パフォーマンスが向上しています。

📦 uvパッケージ管理

現代的なPythonパッケージ管理ツールであるuvを採用しています。

🔧 環境設定

開発/本番環境の切り替えと、.envファイルによる設定管理をサポートしています。

📊 ログシステム

コンソールとファイルの両方への出力をサポートし、自動ローテーションと圧縮機能があります。

🛡️ 型安全

完全な型注釈をサポートしています。

📦 インストール

上述の「🔧 インストール手順」に従ってインストールしてください。

💻 使用例

1️⃣ 小红书にログインする

初回使用時は、小红书アカウントにログインする必要があります：

# ログインツールを使用する
uv run python -m src.xiaohongshu_mcp_python.login

2️⃣ MCP接続を検証する

MCP Inspectorを使用して接続を検証します：

npx @modelcontextprotocol/inspector

ブラウザで http://localhost:18060/mcp にアクセスして接続テストを行います。

3️⃣ コンテンツ投稿の例

画像付きの文章を投稿する：

# MCPツールを介して呼び出す
{
  "tool": "publish_content",
  "parameters": {
    "title": "春日美景",
    "content": "今日撮影した美しい春の景色を共有します。皆さんが気に入ってくれることを願っています！",
    "images": [
      "/path/to/spring1.jpg",
      "/path/to/spring2.jpg"
    ],
    "tags": ["春", "写真撮影", "美しい景色"]
  }
}

📚 ドキュメント

📝 コンテンツ投稿機能

🔍 コンテンツ管理機能

🔌 MCPクライアントの接続

Claude Code CLI

# MCPサービスを追加する
claude mcp add --transport http xiaohongshu-mcp-python http://localhost:18060/mcp

# 接続を検証する
claude mcp list

Cursor IDE

プロジェクトのルートディレクトリに .cursor/mcp.json を作成します：

{
  "mcpServers": {
    "xiaohongshu-mcp-python": {
      "url": "http://localhost:18060/mcp",
      "description": "小红书Python MCPサービス"
    }
  }
}

VSCode

プロジェクトのルートディレクトリに .vscode/mcp.json を作成します：

{
  "servers": {
    "xiaohongshu-mcp-python": {
      "url": "http://localhost:18060/mcp",
      "type": "http"
    }
  }
}

🛠️ 開発ガイド

📁 プロジェクト構造

xiaohongshu-mcp-python/
├── src/
│   └── xiaohongshu_mcp_python/
│       ├── __init__.py
│       ├── main.py              # メインプログラムのエントリーポイント
│       ├── mcp_server.py        # MCPサーバーの実装
│       ├── xiaohongshu/         # 小红书の操作モジュール
│       ├── utils/               # ユーティリティ関数
│       └── config/              # 設定管理
├── tests/                       # テストファイル
├── docs/                        # ドキュメント
├── pyproject.toml              # プロジェクト設定
├── .env.example                # 環境変数のサンプル（開発/本番環境設定）
├── .env                        # 環境変数ファイル（自分で作成する必要があり、.gitignoreに追加されています）
└── README.md

🧪 テストの実行

# すべてのテストを実行する
uv run pytest

# 特定のテストを実行する
uv run pytest tests/test_mcp_server.py

# カバレッジレポートを生成する
uv run pytest --cov=src

🔍 コード品質のチェック

# コードのフォーマットを整える
uv run black src tests

# 型チェックを行う
uv run mypy src

# コードスタイルのチェックを行う
uv run flake8 src tests

🔧 利用可能なMCPツール

📝 ツールの詳細説明

xiaohongshu_publish_video - 動画投稿ツール

小红书プラットフォームに動画を投稿します。

パラメータの説明：

• title (必須): 動画のタイトル、最大20文字の中国語または英単語。
• content (必須): 動画の説明内容、#で始まるタグを含みません。
• video (必須): 動画ファイルのパス、ローカルの動画ファイルの絶対パスをサポートします。
• tags (オプション): トピックタグのリスト、例: ["美食", "旅行", "生活"]
• username (オプション): ユーザー名、指定しない場合はグローバルユーザーが使用されます。

使用例：

# MCPクライアントを介して呼び出す
result = await xiaohongshu_publish_video(
    title="私の旅行動画",
    content="素敵な旅行の時間を共有します",
    video="/path/to/my_video.mp4",
    tags=["旅行", "生活", "素敵な時間"]
)

戻り値：

{
    "success": true,
    "message": "動画の投稿が完了しました",
    "result": {
        "note_id": "動画投稿のID",
        "success": true
    }
}

⚠️ 注意事項

🔒 アカウントセキュリティ

• 同じアカウントで複数のブラウザで同時にログインしないでください。
• 定期的にログイン状態を確認し、Cookieの有効期限切れを適切に処理してください。
• 自動化操作には専用の小红书アカウントを使用することをお勧めします。

📊 投稿制限

• タイトルは20文字以内にしてください。
• 1日の投稿量は適切な範囲に抑えることをお勧めします。
• 画像形式：JPG、PNG、GIF、WebP
• 動画形式：MP4、MOV、AVI（1GB以下を推奨）

🔐 環境モードのベストプラクティス

開発環境（development）

• ✅ ヘッド付きブラウザを使用して、デバッグと観察を容易にします。
• ✅ DEBUGレベルのログを使用して、詳細な実行過程を確認します。
• ✅ ローカル開発と問題のトラブルシューティングに適しています。

本番環境（production）

• ✅ ヘッドレスブラウザを使用して、リソースを節約します。
• ✅ INFOレベルのログを使用して、ログ量を減らします。
• ✅ サーバーデプロイと自動化実行に適しています。

環境切り替えの提案

# ローカル開発
ENV=development python -m xiaohongshu_mcp_python.main

# サーバーデプロイ
ENV=production python -m xiaohongshu_mcp_python.main

# または.envファイルを使用する
# 開発時：.env で ENV=development を設定する
# 本番時：.env で ENV=production を設定する

🛡️ リスク注意

このプロジェクトは学習と研究目的でのみ使用されることを想定しています。小红书のプラットフォーム規則と関連する法律を遵守してください。このツールを使用して生じた損害については、ユーザー自身が責任を負います。

🤝 貢献ガイド

IssueとPull Requestの提出を歓迎します！

1. このプロジェクトをForkする
2. 機能ブランチを作成する：git checkout -b feature/amazing-feature
3. 変更をコミットする：git commit -m 'Add amazing feature'
4. ブランチをプッシュする：git push origin feature/amazing-feature
5. Pull Requestを提出する

📄 ライセンス

このプロジェクトはMITライセンスの下で公開されています。詳細は LICENSE ファイルを参照してください。

🙏 謝辞

• Model Context Protocol が提供するプロトコル標準に感謝します。
• Playwright が提供するブラウザ自動化ツールに感謝します。
• uv が提供する現代的なPythonパッケージ管理ツールに感謝します。

⭐ このプロジェクトが役に立った場合は、Starをしてください！