Servidor MCP de Threads

threads-mcp es un servidor MCP stdio para la API oficial de Threads. Está diseñado para mantenerse fiel a la documentación publicada de Meta Threads, al tiempo que expone una superficie de herramientas MCP práctica para autenticación, publicación, lectura, moderación, estadísticas, descubrimiento, ubicaciones y diagnósticos de configuración.

La versión actual está limitada intencionalmente a las capacidades de Threads documentadas oficialmente y a la colección oficial de Postman. No depende de endpoints de respaldo no documentados ni de envoltorios de conveniencia que serían difíciles de mantener en un paquete público.

Aspectos destacados

• Solo alcance de la API oficial de Threads

• Herramientas MCP para autenticación, búsqueda de perfiles, publicación, lectura, respuestas, estadísticas, búsqueda, ubicaciones, oEmbed y diagnósticos

• Entradas de publicación modeladas en camelCase y serializadas internamente a los parámetros snake_case esperados por Threads

• Soporte para publicación de carruseles en varios pasos

• Capa de cliente compartida para reintentos, sondeo (polling), paginación y errores normalizados de la API de Meta

Inicio rápido

1. Instalar dependencias:

npm install

2. Compilar el servidor:

npm run build

3. Crea tu archivo de entorno local y establece al menos THREADS_ACCESS_TOKEN.

4. Si aún necesitas un token, ejecuta el asistente de OAuth local:

npm run auth:token

5. Inicia el servidor:

node dist/index.js

6. Llama a validate_setup antes de usar los flujos de publicación o moderación con una cuenta real.

Catálogo de herramientas

Autenticación

• exchange_code_for_token

• get_long_lived_access_token

• refresh_access_token

• get_app_access_token

Perfiles y descubrimiento

• get_me

• get_profile

• get_profile_threads

Publicación y ciclo de vida

• get_publishing_limit

• create_thread_container

• publish_thread

• create_and_publish_thread

• repost_thread

• delete_thread

Lectura y respuestas

• get_threads

• get_thread

• get_replies

• get_thread_conversation

• get_pending_replies

• manage_reply

• manage_pending_reply

Estadísticas, búsqueda y embebidos

• get_user_insights

• get_thread_insights

• search_threads

• get_mentions

• get_oembed

Ubicaciones y diagnósticos

• search_locations

• get_location

• validate_setup

Explícitamente fuera del alcance para la v1

• Webhooks

• Alojamiento de callback de OAuth embebido

• Cualquier endpoint de respaldo no documentado o funciones de conveniencia que no estén cubiertas por la documentación oficial o la colección oficial de Postman

Arquitectura

El servidor está dividido en unas pocas capas claras:

• src/index.ts arranca el transporte stdio de MCP.

• src/threads/client.ts gestiona las llamadas HTTP autenticadas, reintentos, paginación, sondeo y errores normalizados de la API de Meta.

• src/tools/ contiene un módulo por familia de herramientas además de esquemas compartidos.

El modelo de entrada de publicación se expone como una unión discriminada pública única que cubre text, image, video, carousel y reply.

Requisitos previos

Necesitas todo lo siguiente antes de que el servidor pueda realizar llamadas a la API en vivo:

• Una aplicación de Meta configurada para el caso de uso de Threads

• Un token de acceso de usuario de Threads para la cuenta en la que deseas operar

• Acceso avanzado y revisión de la aplicación donde tu integración lo requiera

• Node.js 20+ en la máquina donde se ejecutará el servidor

Variables de entorno

Requeridas para la mayoría de las herramientas de token de usuario:

• THREADS_ACCESS_TOKEN

Opcionales:

• THREADS_APP_ID

• THREADS_APP_SECRET

• THREADS_REDIRECT_URI

• THREADS_API_BASE_URL

• THREADS_USER_ID

• THREADS_MAX_RETRIES

• THREADS_RETRY_BASE_DELAY_MS

• THREADS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_POLL_INTERVAL_MS

Copia .env.example y establece al menos el token de acceso. THREADS_APP_ID y THREADS_APP_SECRET también son necesarios para las herramientas de ayuda de autenticación y para get_oembed cuando no pasas un token de acceso de aplicación explícito.

Dónde obtener THREADS_APP_ID

• Abre tu aplicación en el panel de Meta for Developers: https://developers.facebook.com/apps/

• Abre la aplicación creada con el caso de uso Threads

• Ve a Use Cases -> Threads -> Customize -> Settings

• Copia el Threads App ID de esa página

• Usa ese valor como THREADS_APP_ID

Importante:

• No uses el ID de aplicación general de Meta del panel de control o la página de configuración de nivel superior

• Usa las credenciales específicas del caso de uso de Threads desde Use Cases -> Threads -> Customize -> Settings

THREADS_APP_SECRET proviene de la misma página de configuración del caso de uso de Threads. Mantenlo privado.

Script de ayuda de tokens

El repositorio incluye un asistente de OAuth local que sigue el flujo de token de acceso de Meta Threads:

1. Abre la ventana de autorización de Threads

2. Recibe el código de autorización en una URL de callback local

3. Intercámbialo por un token de corta duración

4. Intercámbialo por un token de larga duración

5. Guarda el resultado en .env como THREADS_ACCESS_TOKEN

Configuración:

• Añade tus credenciales de aplicación de Meta a .env

• Asegúrate de que la URI de redirección de OAuth válida de tu aplicación coincida con THREADS_REDIRECT_URI

Ejecución:

npm run auth:token

Flags opcionales:

• --redirect-uri http://127.0.0.1:8788/callback

• --env-file .env.local

• --no-open

Alcances requeridos por familia de herramientas

• threads_basic Utilizado por get_me, get_profile, get_threads, get_thread y la validación de configuración base.

• threads_content_publish Utilizado por get_publishing_limit, create_thread_container, publish_thread y create_and_publish_thread.

• threads_read_replies Utilizado por get_replies y pruebas seguras de lectura de respuestas en validate_setup.

• threads_manage_replies Utilizado por manage_reply.

• threads_manage_insights Utilizado por get_user_insights y get_thread_insights.

• threads_keyword_search Utilizado por search_threads.

• threads_profile_discovery Utilizado por get_profile y get_profile_threads para escenarios de descubrimiento de cuentas públicas.

• threads_location_tagging Utilizado por search_locations, get_location y flujos de publicación que establecen locationId.

• threads_delete Utilizado por delete_thread.

validate_setup realiza pruebas seguras para inferir el acceso para threads_basic, threads_content_publish, threads_read_replies, threads_manage_insights, threads_keyword_search, threads_profile_discovery y threads_location_tagging. Deliberadamente no realiza pruebas destructivas para threads_manage_replies o threads_delete, por lo que esos alcances no se validan activamente mediante la configuración.

Comportamiento de publicación

El servidor modela las opciones de contenedor oficiales en camelCase y las serializa internamente a los parámetros snake_case esperados por la API de Threads.

Las entradas admitidas incluyen:

• Campos comunes: text, replyControl, replyToId, quotePostId, topicTag, locationId, textEntities, allowlistedCountryCodes

• Campos solo de texto: linkAttachment, pollAttachment, textAttachment, gifAttachment, enableReplyApprovals, autoPublishText, isGhostPost

• Campos de imagen o video: imageUrl, videoUrl, altText, isSpoilerMedia

• Elementos de carrusel: arrays validados de elementos de imagen o video con campos multimedia por elemento

La publicación de carruseles sigue el flujo oficial de varios pasos:

1. Crear un contenedor de elemento por imagen o video con is_carousel_item=true

2. Crear el contenedor de carrusel padre con children=[...]

3. Publicar el contenedor padre

Notas de cobertura

El repositorio cubre actualmente estas familias de la API oficial de Threads:

• Asistentes de autorización

• Publicación, incluyendo publicaciones de cita, publicación de reposts y sondeo de estado de contenedor

• Búsqueda de perfil de usuario y recuperación de publicaciones de perfil público

• Recuperación de medios de Threads

• Recuperación de respuestas, conversaciones aplanadas, respuestas pendientes, ocultar y mostrar, y flujos de aprobación e ignorar

• Estadísticas de usuario y de publicación

• Búsqueda por palabras clave y menciones

• Búsqueda de ubicaciones y recuperación de ubicaciones

• oEmbed

• Diagnósticos de configuración

Ejemplo de configuración local de MCP

Ejemplo de configuración al estilo de Claude Desktop:

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/absolute/path/to/threads-mcp/dist/index.js"],
      "env": {
        "THREADS_ACCESS_TOKEN": "thdt_your_user_access_token",
        "THREADS_APP_ID": "optional_app_id",
        "THREADS_APP_SECRET": "optional_app_secret"
      }
    }
  }
}

Si más adelante publicas este paquete como una CLI, el command puede convertirse en threads-mcp.

Publicación

Los metadatos del paquete ya están configurados para la publicación en npm como un paquete público:

• nombre del paquete: threads-mcp

• versión actual: 0.0.0

• punto de entrada CLI: threads-mcp

• acceso de publicación: public

Antes de publicar, ejecuta:

npm run build
npm test
npm publish --access public

prepublishOnly está configurado para ejecutar los pasos de compilación y prueba automáticamente durante npm publish.

Desarrollo

Instala las dependencias una vez que Node.js esté disponible:

npm install
npm run build
npm test

Verificaciones manuales sugeridas:

1. Ejecuta npm run build para verificar la compilación de TypeScript.

2. Ejecuta npm test para ejecutar las pruebas de esquema, cliente y registro de herramientas.

3. Inicia el servidor con node dist/index.js.

4. Llama primero a validate_setup con un token real.

5. Prueba create_thread_container y publish_thread con una cuenta de Threads de prueba.

Limitaciones conocidas

• El transporte es solo stdio en la v1

• No hay un servidor de callback de OAuth embebido; los asistentes de intercambio de tokens se exponen como herramientas MCP en su lugar

• validate_setup no puede verificar de forma segura threads_manage_replies sin realizar una llamada de moderación que cambie el estado

• validate_setup tampoco realiza una prueba de eliminación que cambie el estado

• create_and_publish_thread rechaza intencionalmente autoPublishText=true porque ese flag entra en conflicto con el contrato explícito de dos pasos de la herramienta

• La publicación de respuestas se modela como una variante dedicada reply respaldada por el parámetro oficial reply_to_id y actualmente apunta a respuestas de texto en el esquema público

• La verificación del comportamiento de la API en vivo sigue dependiendo de credenciales de aplicación válidas, alcances aprobados y una cuenta de Threads real

Fuentes utilizadas para el alcance de la API y la selección de endpoints

• Referencia de la API de Meta Threads: https://developers.facebook.com/docs/threads/reference

• Referencia de publicación de Meta Threads: https://developers.facebook.com/docs/threads/reference/publishing

• Espacio de trabajo oficial de Postman de Meta Threads: https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api