douyin-dm-mcp

Ein Model Context Protocol-Server und eine lokale HTTP-API für Douyin-Web-Direktnachrichten, erstellt mit Playwright. Beide Schnittstellen verwenden dasselbe persistente lokale Browserprofil, lesen aktuell gerenderte Konversationen und Nachrichten und senden einzelne Nachrichten nur, wenn dies explizit aktiviert ist.

Das Projekt verwendet die aktuelle eigenständige Chat-Seite von Douyin:

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

Login- und Kontostatusprüfungen verwenden weiterhin die Douyin-Startseite. /messages gibt derzeit eine 404-Seite zurück und wird nicht für die Automatisierung verwendet.

Sicherheitsgrenzen

• DOUYIN_ALLOW_SEND ist standardmäßig false, sodass echtes Senden standardmäßig deaktiviert ist.

• send_message verwendet standardmäßig dryRun: true. Trockenläufe validieren den aktuellen Snapshot, ohne eine Konversation zu öffnen oder den Seitenzustand zu ändern.

• Ein echtes Senden erfordert sowohl deaktivierten Trockenlauf als auch DOUYIN_ALLOW_SEND=true.

• Vor dem Lesen oder einem echten Senden überprüft der Server, dass der Spitzname eindeutig ist, die Konversationsposition und der exakte Spitzname noch übereinstimmen und der geöffnete Chat-Titel übereinstimmt.

• Doppelte Spitznamen werden als targetable: false markiert und von beiden MCP-Tools und der spitznamenbasierten CLI abgelehnt.

• Wenn das Ergebnis nach dem Klicken auf Senden nicht bestätigt werden kann, gibt der Server SEND_STATUS_UNKNOWN zurück und wiederholt nicht automatisch.

• Jedes Browserprofil hat eine exklusive Dateisystemsperre, um zu verhindern, dass gleichzeitige Chromium-Instanzen es beschädigen. MCP, die HTTP-API und die Operator-CLI können nicht gleichzeitig mit demselben DOUYIN_PROFILE ausgeführt werden.

• Alle Seitenoperationen werden serialisiert, um konversationsübergreifende Lese- oder Sendeoperationen zu verhindern.

• Das Projekt ändert keine Browser-Fingerprints, umgeht keine Verifizierungsherausforderungen und ruft keine privaten WebSocket/Protobuf-Schnittstellen von Douyin auf.

• Logs werden auf stderr geschrieben und redigieren Nachrichteninhalte, Cookies und Passwortfelder.

Related MCP server: dy-mcp

Aktuelle Einschränkungen

Das gerenderte Konversations-DOM von Douyin bietet keine unterstützte stabile Konversations-ID, Benutzer-ID, sec_uid oder einen stabilen Profillink. Daher:

• conversationKey ist undurchsichtig und nur für den neuesten list_conversations-Snapshot gültig.

• Der Aufruf von list_conversations erstellt neue Schlüssel und lässt jeden Schlüssel aus dem vorherigen Snapshot sofort ablaufen.

• Jede Konversation gibt stableKey: false zurück; doppelte Spitznamen geben zusätzlich targetable: false zurück.

• Rufen Sie list_conversations auf, bevor Sie read_messages oder send_message aufrufen, und verwenden Sie dann einen Schlüssel aus genau diesem Ergebnis.

• Die Konversationsliste enthält nur Elemente, die derzeit vom Browser gerendert werden; complete ist immer false.

• Unscharfe Spitznamenübereinstimmung, Massenversand, Fremdsuche und Such-zum-Senden-Fallbacks werden absichtlich nicht unterstützt.

Detaillierte Live-Seiten-Beweise sind in RESEARCH.md dokumentiert.

Anforderungen

• Node.js 20 oder neuer

• npm

• Eine Desktop-Umgebung, die Chromium für den anfänglichen QR-Code-Login anzeigen kann

Installation

npm install
npx playwright install chromium
npm run build

Konfiguration

Diese Variablen werden aus der Prozessumgebung gelesen. Das Projekt lädt keine .env-Datei. Verwenden Sie .env.example als Referenz und exportieren Sie die Werte in Ihrer Shell oder setzen Sie sie im env-Block des MCP-Clients.

Browserdaten werden gespeichert in:

.data/profiles/<DOUYIN_PROFILE>

Dieses Verzeichnis enthält Authentifizierungsdaten. Committen oder teilen Sie es nicht.

Login

Für die erste Verwendung oder eine abgelaufene Sitzung führen Sie aus:

npm run login

Scannen Sie den angezeigten QR-Code mit Douyin. Nach dem Login gibt das Skript einen strukturierten Status aus, schließt Chromium sicher und behält die authentifizierte Sitzung im persistenten Profil.

Aktuelle Sitzung prüfen:

npm run status

Beispiel für ein erfolgreiches Ergebnis:

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

Starten des MCP-Servers

Der kompilierte Einstiegspunkt ist:

node dist/index.js

Codex-CLI-Beispiel:

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

Generische MCP-Client-Konfiguration:

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

Für ein autorisiertes echtes Senden setzen Sie DOUYIN_ALLOW_SEND für diesen MCP-Prozess auf true und starten Sie ihn neu. Lassen Sie das Senden nicht global aktiviert.

Starten Sie diesen Prozess nicht, während die HTTP-API oder die CLI bereits dieselbe Profilsperre hält.

Starten der HTTP-API

Aus dem Quellcode ausführen:

npm run api

Oder den kompilierten Einstiegspunkt ausführen:

node dist/api.js

Starten Sie diesen Prozess nicht, während MCP oder die CLI bereits dieselbe Profilsperre hält.

Die Standard-Basis-URL ist http://127.0.0.1:3000. Der nicht authentifizierte Health-Check ist:

curl http://127.0.0.1:3000/health

API-Routen:

POST-Anfragen erfordern Content-Type: application/json. Das Senden bleibt standardmäßig ein Trockenlauf. Ein echtes Senden erfordert weiterhin sowohl "dryRun": false als auch DOUYIN_ALLOW_SEND=true.

Beispiel:

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}'

Loopback-Zugriff erfordert keinen API-Schlüssel. Das Binden an einen anderen Host wird verweigert, es sei denn, DOUYIN_API_KEY ist auf mindestens 16 Zeichen gesetzt. Wenn konfiguriert, senden Sie ihn bei jeder /api/v1/*-Anfrage:

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

Die API gibt dieselben strukturierten Erfolgs- und Douyin-Fehlerobjekte wie MCP zurück. Parsing-Fehler verwenden INVALID_REQUEST, INVALID_JSON, UNSUPPORTED_MEDIA_TYPE oder PAYLOAD_TOO_LARGE; Authentifizierungsfehler verwenden UNAUTHORIZED.

MCP-Tools

browser_status

Prüft, ob das persistente Douyin-Browserprofil authentifiziert ist.

Eingabe: keine.

list_conversations

Öffnet die eigenständige Chat-Seite und gibt aktuell gerenderte Konversationen mit undurchsichtigen conversationKey-Werten für den neuen Snapshot zurück.

{
  "limit": 20
}

Konversationsfelder:

• conversationKey

• stableKey, derzeit immer false

• position

• nickname

• preview

• timestamp

• targetable, false, wenn doppelte Spitznamen eine sichere Auswahl unmöglich machen

read_messages

Liest aktuell sichtbare Nachrichten aus einer von list_conversations zurückgegebenen Konversation.

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

Nachrichtenfelder:

• direction: incoming oder outgoing, aus verifizierten sender-seitigen DOM-Beweisen

• type: text oder unsupported für nicht erkannte Nachrichtentypen

• content: sichtbarer Text oder null, wenn leer

Konversationen mit targetable: false werden abgelehnt.

send_message

Sendet eine Nachricht an eine verifizierte Konversation.

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

Ein echtes Senden erfordert alle folgenden Bedingungen:

1. DOUYIN_ALLOW_SEND=true.

2. dryRun=false.

3. Der Ziel-Spitzname ist im aktuellen Snapshot eindeutig.

4. Die Konversationsposition und der exakte Spitzname stimmen weiterhin mit dem Snapshot überein.

5. Der geöffnete Chat-Titel stimmt exakt mit dem Ziel-Spitznamen überein.

6. Die Nachricht hat keine führenden oder nachfolgenden Leerzeichen.

7. Der logische Slate-Editor-Text stimmt exakt mit dem angeforderten Text überein.

Nach dem Klicken auf Senden wartet der Server auf eine neue ausgehende Nachricht mit dem exakten kanonischen Text. Wenn die Bestätigung fehlschlägt, gibt er SEND_STATUS_UNKNOWN zurück; Aufrufer müssen die Konversation manuell prüfen, anstatt automatisch zu wiederholen. Das Mindestsendeintervall bleibt über Aktualisierungen der Konversationsliste hinweg erhalten.

Operator-CLI

Aktuell gerenderte Konversationen auflisten:

npm run chat -- list

Nachrichten nach einem exakten, eindeutigen Spitznamen lesen:

npm run chat -- read "Exact nickname"

Echtes Senden erfordert ebenfalls DOUYIN_ALLOW_SEND. PowerShell-Beispiel:

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

Die CLI akzeptiert nur exakte Spitznamen und weigert sich fortzufahren, wenn keine Übereinstimmung oder mehrere Übereinstimmungen gefunden werden.

Führen Sie die CLI nicht aus, während MCP oder die HTTP-API bereits dieselbe Profilsperre hält.

Entwicklung

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

Die Tests decken Konfigurationsparsing, strukturierte Fehler, Profilsperre, Serialisierung von Seitenoperationen, Snapshot-Ablauf, Ablehnung von Duplikaten, Zielverifizierung, Nachrichtenrichtung, Trockenlauf-Isolation, Composer-Rollback, erfolgreiche Sende-Bestätigung, unbekannten Sendestatus, persistente Ratenbegrenzung und paketsichere Standardwerte ab.

Projektstruktur

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

Lizenz

Lizenziert unter der freizügigen MIT-Lizenz.