douyin-dm-mcp

Un servidor de Model Context Protocol y una API HTTP local para los mensajes directos web de Douyin, construido con Playwright. Ambas interfaces reutilizan el mismo perfil de navegador local persistente, leen las conversaciones y mensajes actualmente renderizados, y envían mensajes individuales solo cuando se habilita explícitamente.

El proyecto utiliza la página de chat independiente actual de Douyin:

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

El inicio de sesión y las comprobaciones de estado de la cuenta siguen usando la página de inicio de Douyin. /messages actualmente devuelve una página 404 y no se utiliza para la automatización.

Límites de seguridad

• DOUYIN_ALLOW_SEND tiene como valor predeterminado false, por lo que el envío real está deshabilitado por defecto.

• send_message tiene como valor predeterminado dryRun: true. Las ejecuciones en seco validan la instantánea actual sin abrir una conversación ni cambiar el estado de la página.

• Un envío real requiere tanto que la ejecución en seco esté deshabilitada como que DOUYIN_ALLOW_SEND=true.

• Antes de leer o de un envío real, el servidor verifica que el apodo sea único, que la posición de la conversación y el apodo exacto sigan coincidiendo, y que el título del chat abierto coincida.

• Los apodos duplicados se marcan como targetable: false y son rechazados tanto por las herramientas MCP como por la CLI basada en apodos.

• Si el resultado no se puede confirmar después de hacer clic en enviar, el servidor devuelve SEND_STATUS_UNKNOWN y no reintenta automáticamente.

• Cada perfil de navegador tiene un bloqueo exclusivo del sistema de archivos para evitar que instancias concurrentes de Chromium lo corrompan. MCP, la API HTTP y la CLI del operador no pueden ejecutarse al mismo tiempo contra el mismo DOUYIN_PROFILE.

• Todas las operaciones de página están serializadas para evitar lecturas o envíos entre conversaciones.

• El proyecto no modifica las huellas del navegador, no evita los desafíos de verificación ni llama a las interfaces privadas de WebSocket/Protobuf de Douyin.

• Los registros se escriben en stderr y redactan los cuerpos de los mensajes, las cookies y los campos de contraseña.

Related MCP server: dy-mcp

Limitaciones actuales

El DOM de la conversación renderizada de Douyin no expone un ID de conversación estable compatible, ID de usuario, sec_uid ni un enlace de perfil estable. Por lo tanto:

• conversationKey es opaco y solo es válido para la última instantánea de list_conversations.

• Llamar a list_conversations crea nuevas claves y expira inmediatamente todas las claves de la instantánea anterior.

• Cada conversación devuelve stableKey: false; los apodos duplicados además devuelven targetable: false.

• Llame a list_conversations antes de llamar a read_messages o send_message, y luego use una clave de ese resultado exacto.

• La lista de conversaciones contiene solo los elementos actualmente renderizados por el navegador; complete siempre es false.

• La coincidencia difusa de apodos, el envío masivo, la búsqueda de extraños y los respaldos de búsqueda para envío no se admiten intencionalmente.

La evidencia detallada de la página en vivo está registrada en RESEARCH.md.

Requisitos

• Node.js 20 o más reciente

• npm

• Un entorno de escritorio capaz de mostrar Chromium para el inicio de sesión inicial con código QR

Instalación

npm install
npx playwright install chromium
npm run build

Configuración

Estas variables se leen del entorno del proceso. El proyecto no carga .env. Use .env.example como referencia, luego exporte los valores en su shell o configúrelos en el bloque env del cliente MCP.

Los datos del navegador se almacenan en:

.data/profiles/<DOUYIN_PROFILE>

Este directorio contiene datos de autenticación. No lo confirme ni lo comparta.

Inicio de sesión

Para el primer uso o una sesión caducada, ejecute:

npm run login

Escanee el código QR mostrado con Douyin. Después del inicio de sesión, el script imprime el estado estructurado, cierra Chromium de forma segura y mantiene la sesión autenticada en el perfil persistente.

Compruebe la sesión actual:

npm run status

Ejemplo de resultado exitoso:

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

Iniciar el servidor MCP

El punto de entrada compilado es:

node dist/index.js

Ejemplo de Codex CLI:

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

Configuración genérica del cliente MCP:

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

Para un envío real autorizado, establezca DOUYIN_ALLOW_SEND en true para ese proceso MCP y reinícielo. No deje el envío habilitado globalmente.

No inicie este proceso mientras la API HTTP o la CLI ya tengan el mismo bloqueo de perfil.

Iniciar la API HTTP

Ejecute desde el código fuente:

npm run api

O ejecute el punto de entrada compilado:

node dist/api.js

No inicie este proceso mientras MCP o la CLI ya tengan el mismo bloqueo de perfil.

La URL base predeterminada es http://127.0.0.1:3000. La comprobación de salud sin autenticación es:

curl http://127.0.0.1:3000/health

Rutas de la API:

Las solicitudes POST requieren Content-Type: application/json. El envío sigue siendo una ejecución en seco por defecto. Un envío real aún requiere tanto "dryRun": false como DOUYIN_ALLOW_SEND=true.

Ejemplo:

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

El acceso loopback no requiere una clave de API. El enlace a cualquier otro host se rechaza a menos que DOUYIN_API_KEY esté configurada con al menos 16 caracteres. Cuando esté configurada, envíela en cada solicitud /api/v1/*:

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

La API devuelve los mismos objetos de éxito estructurado y error de Douyin que MCP. Los errores de análisis de solicitudes usan INVALID_REQUEST, INVALID_JSON, UNSUPPORTED_MEDIA_TYPE o PAYLOAD_TOO_LARGE; los fallos de autenticación usan UNAUTHORIZED.

Herramientas MCP

browser_status

Comprueba si el perfil de navegador persistente de Douyin está autenticado.

Entrada: ninguna.

list_conversations

Abre la página de chat independiente y devuelve las conversaciones actualmente renderizadas con valores opacos de conversationKey para la nueva instantánea.

{
  "limit": 20
}

Campos de la conversación:

• conversationKey

• stableKey, actualmente siempre false

• position

• nickname

• preview

• timestamp

• targetable, false cuando los apodos duplicados hacen imposible la selección segura

read_messages

Lee los mensajes actualmente visibles de una conversación devuelta por list_conversations.

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

Campos del mensaje:

• direction: incoming o outgoing, según evidencia verificada del DOM del lado del remitente

• type: text, o unsupported para tipos de mensaje no reconocidos

• content: texto visible, o null cuando está vacío

Las conversaciones con targetable: false son rechazadas.

send_message

Envía un mensaje a una conversación verificada.

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

Un envío real requiere todo lo siguiente:

1. DOUYIN_ALLOW_SEND=true.

2. dryRun=false.

3. El apodo objetivo es único en la instantánea actual.

4. La posición de la conversación y el apodo exacto aún coinciden con la instantánea.

5. El título del chat abierto coincide exactamente con el apodo objetivo.

6. El mensaje no tiene espacios en blanco al principio ni al final.

7. El texto lógico del editor Slate coincide exactamente con el texto solicitado.

Después de hacer clic en enviar, el servidor espera un nuevo mensaje saliente con el texto canónico exacto. Si la confirmación falla, devuelve SEND_STATUS_UNKNOWN; los llamadores deben inspeccionar la conversación manualmente en lugar de reintentar automáticamente. El intervalo mínimo de envío se mantiene entre actualizaciones de la lista de conversaciones.

CLI del operador

Listar las conversaciones actualmente renderizadas:

npm run chat -- list

Leer mensajes por un apodo exacto y único:

npm run chat -- read "Exact nickname"

Los envíos reales también requieren DOUYIN_ALLOW_SEND. Ejemplo de PowerShell:

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

La CLI acepta solo apodos exactos y se niega a continuar cuando no hay coincidencia o se encuentran múltiples coincidencias.

No ejecute la CLI mientras MCP o la API HTTP ya tengan el mismo bloqueo de perfil.

Desarrollo

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

Las pruebas cubren el análisis de configuración, errores estructurados, bloqueo de perfil, serialización de operaciones de página, caducidad de instantáneas, rechazo de duplicados, verificación de objetivos, dirección de mensajes, aislamiento de ejecución en seco, reversión del compositor, confirmación exitosa de envío, estado de envío desconocido, limitación de velocidad persistente y valores predeterminados seguros para el paquete.

Estructura del proyecto

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

Licencia

Licenciado bajo la permisiva Licencia MIT.