douyin-dm-mcp

Douyin（抖音）のWebダイレクトメッセージ向けのModel Context ProtocolサーバーおよびローカルHTTP APIです。Playwrightで構築されています。両インターフェースは同じ永続的なローカルブラウザプロファイルを再利用し、現在レンダリングされている会話とメッセージを読み取り、明示的に有効化された場合にのみ個別メッセージを送信します。

このプロジェクトはDouyinの現在のスタンドアロンチャットページを使用します：

https://www.douyin.com/chat?isPopup=1

ログインとアカウント状態の確認は引き続きDouyinのホームページを使用します。/messages は現在404ページを返すため、自動化には使用されません。

安全上の境界

• DOUYIN_ALLOW_SEND はデフォルトで false のため、実際の送信はデフォルトで無効です。

• send_message はデフォルトで dryRun: true です。ドライランは会話を開いたりページ状態を変更したりせずに、現在のスナップショットを検証します。

• 実際の送信には、ドライランの無効化と DOUYIN_ALLOW_SEND=true の両方が必要です。

• 読み取りまたは実際の送信の前に、サーバーはニックネームが一意であること、会話の位置と正確なニックネームがまだ一致していること、開いているチャットのタイトルが一致していることを検証します。

• 重複するニックネームは targetable: false とマークされ、MCPツールとニックネームベースのCLIの両方で拒否されます。

• 送信クリック後に結果を確認できない場合、サーバーは SEND_STATUS_UNKNOWN を返し、自動的に再試行しません。

• 各ブラウザプロファイルには排他的なファイルシステムロックがあり、同時に実行されるChromiumインスタンスによる破損を防ぎます。MCP、HTTP API、オペレーターCLIは、同じ DOUYIN_PROFILE に対して同時に実行できません。

• すべてのページ操作は直列化され、会話をまたいだ読み取りや送信を防ぎます。

• このプロジェクトはブラウザのフィンガープリントを変更したり、認証チャレンジを回避したり、DouyinのプライベートなWebSocket/Protobufインターフェースを呼び出したりしません。

• ログはstderrに書き込まれ、メッセージ本文、Cookie、パスワードフィールドを編集します。

Related MCP server: dy-mcp

現在の制限

Douyinのレンダリングされた会話DOMは、サポートされている安定した会話ID、ユーザーID、sec_uid、または安定したプロフィールリンクを公開しません。したがって：

• conversationKey は不透明であり、最新の list_conversations スナップショットに対してのみ有効です。

• list_conversations を呼び出すと新しいキーが作成され、前のスナップショットのすべてのキーが直ちに失効します。

• すべての会話は stableKey: false を返します。重複するニックネームはさらに targetable: false を返します。

• read_messages または send_message を呼び出す前に list_conversations を呼び出し、その正確な結果のキーを使用してください。

• 会話リストには、ブラウザに現在レンダリングされている項目のみが含まれます。complete は常に false です。

• あいまいなニックネームマッチング、一括送信、見知らぬ人検索、検索から送信へのフォールバックは意図的にサポートされていません。

詳細なライブページの証拠は RESEARCH.md に記録されています。

要件

• Node.js 20以降

• npm

• 初期QRコードログイン用にChromiumを表示できるデスクトップ環境

インストール

npm install
npx playwright install chromium
npm run build

設定

これらの変数はプロセス環境から読み取られます。このプロジェクトは .env を読み込みません。.env.example を参照として使用し、シェルで値をエクスポートするか、MCPクライアントの env ブロックで設定してください。

ブラウザデータは次の場所に保存されます：

.data/profiles/<DOUYIN_PROFILE>

このディレクトリには認証データが含まれています。コミットしたり共有したりしないでください。

ログイン

初回使用またはセッションの期限切れの場合、次を実行します：

npm run login

表示されたQRコードをDouyinでスキャンします。ログイン後、スクリプトは構造化されたステータスを出力し、Chromiumを安全に閉じ、認証済みセッションを永続プロファイルに保持します。

現在のセッションを確認：

npm run status

成功した結果の例：

{
  "ok": true,
  "browserRunning": true,
  "loggedIn": true,
  "currentUrl": "https://www.douyin.com/jingxuan"
}

MCPサーバーの起動

コンパイル済みエントリポイントは：

node dist/index.js

Codex CLIの例：

codex mcp add douyin-dm -- node /absolute/path/to/douyin-dm-mcp/dist/index.js

一般的なMCPクライアント設定：

{
  "mcpServers": {
    "douyin-dm": {
      "command": "node",
      "args": ["/absolute/path/to/douyin-dm-mcp/dist/index.js"],
      "env": {
        "DOUYIN_PROFILE": "default",
        "DOUYIN_ALLOW_SEND": "false"
      }
    }
  }
}

実際の送信を許可するには、そのMCPプロセスに対して DOUYIN_ALLOW_SEND を true に設定し、再起動します。送信をグローバルに有効にしたままにしないでください。

HTTP APIまたはCLIが同じプロファイルロックをすでに保持している間は、このプロセスを起動しないでください。

HTTP APIの起動

ソースから実行：

npm run api

またはコンパイル済みエントリポイントを実行：

node dist/api.js

MCPまたはCLIが同じプロファイルロックをすでに保持している間は、このプロセスを起動しないでください。

デフォルトのベースURLは http://127.0.0.1:3000 です。認証なしのヘルスチェック：

curl http://127.0.0.1:3000/health

APIルート：

POSTリクエストには Content-Type: application/json が必要です。送信はデフォルトでドライランのままです。実際の送信には、"dryRun": false と DOUYIN_ALLOW_SEND=true の両方が引き続き必要です。

例：

curl "http://127.0.0.1:3000/api/v1/conversations?limit=20"

curl -X POST http://127.0.0.1:3000/api/v1/messages/read \
  -H "Content-Type: application/json" \
  -d '{"conversationKey":"fallback:...:0","limit":20}'

ループバックアクセスにはAPIキーは不要です。他のホストへのバインドは、DOUYIN_API_KEY が少なくとも16文字に設定されていない限り拒否されます。設定されている場合、すべての /api/v1/* リクエストで送信します：

curl http://127.0.0.1:3000/api/v1/status \
  -H "Authorization: Bearer YOUR_API_KEY"

APIはMCPと同じ構造化された成功およびDouyinエラーオブジェクトを返します。リクエスト解析エラーは INVALID_REQUEST、INVALID_JSON、UNSUPPORTED_MEDIA_TYPE、または PAYLOAD_TOO_LARGE を使用します。認証失敗は UNAUTHORIZED を使用します。

MCPツール

browser_status

永続的なDouyinブラウザプロファイルが認証されているかどうかを確認します。

入力：なし。

list_conversations

スタンドアロンチャットページを開き、現在レンダリングされている会話を、新しいスナップショットの不透明な conversationKey 値とともに返します。

{
  "limit": 20
}

会話フィールド：

• conversationKey

• stableKey、現在は常に false

• position

• nickname

• preview

• timestamp

• targetable、重複するニックネームにより安全な選択が不可能な場合は false

read_messages

list_conversations によって返された会話から、現在表示されているメッセージを読み取ります。

{
  "conversationKey": "fallback:550e8400-e29b-41d4-a716-446655440000:0",
  "limit": 20
}

メッセージフィールド：

• direction: incoming または outgoing。検証済みの送信者側DOM証拠に基づく

• type: text、または認識されないメッセージタイプの場合は unsupported

• content: 表示されるテキスト、空の場合は null

targetable: false の会話は拒否されます。

send_message

検証済みの会話に1つのメッセージを送信します。

{
  "conversationKey": "fallback:550e8400-e29b-41d4-a716-446655440000:0",
  "text": "Test message",
  "dryRun": true
}

実際の送信には、次のすべてが必要です：

1. DOUYIN_ALLOW_SEND=true。

2. dryRun=false。

3. ターゲットのニックネームが現在のスナップショットで一意であること。

4. 会話の位置と正確なニックネームがスナップショットと一致していること。

5. 開いているチャットのタイトルがターゲットのニックネームと完全に一致していること。

6. メッセージに先頭または末尾の空白がないこと。

7. 論理的なSlateエディタのテキストが要求されたテキストと完全に一致していること。

送信クリック後、サーバーは正確な正規テキストを持つ新しい送信メッセージを待ちます。確認が失敗した場合、SEND_STATUS_UNKNOWN を返します。呼び出し元は自動的に再試行する代わりに、手動で会話を検査する必要があります。最小送信間隔は、会話リストの更新をまたいで保持されます。

オペレーターCLI

現在レンダリングされている会話を一覧表示：

npm run chat -- list

正確で一意なニックネームでメッセージを読み取る：

npm run chat -- read "Exact nickname"

実際の送信には DOUYIN_ALLOW_SEND も必要です。PowerShellの例：

$env:DOUYIN_ALLOW_SEND="true"
npm run chat -- send "Exact nickname" "Test message"
Remove-Item Env:DOUYIN_ALLOW_SEND

CLIは正確なニックネームのみを受け入れ、一致しない場合や複数の一致がある場合は続行を拒否します。

MCPまたはHTTP APIが同じプロファイルロックをすでに保持している間は、CLIを実行しないでください。

開発

npm run lint
npm test
npm run build
npm run smoke:mcp

テストは、設定解析、構造化エラー、プロファイルロック、ページ操作の直列化、スナップショットの失効、重複拒否、ターゲット検証、メッセージの方向、ドライランの分離、コンポーザーのロールバック、送信確認の成功、不明な送信ステータス、永続的なレート制限、パッケージ安全なデフォルトをカバーしています。

プロジェクト構造

src/
  browser/          Browser lifecycle, profile locking, and operation serialization
  douyin/           DouyinService, centralized selectors, and page objects
  index.ts          MCP stdio server
  api.ts            HTTP API process entry point
  api/              Versioned HTTP routes, validation, and authentication
scripts/
  login.ts          QR-code login
  status.ts         Authentication status check
  chat.ts           Operator CLI
  mcp-smoke.ts      MCP transport smoke check
tests/unit/         Repeatable behavioral tests
RESEARCH.md         Live-page evidence and engineering research

ライセンス

寛容な MIT License の下でライセンスされています。