threads-mcp

Un servidor MCP para la API de Threads. Hace E/S de plataforma y nada más: publicar una publicación, leer tus propias publicaciones, leer sus estadísticas, comprobar la cuota de publicación. Sin lógica editorial, sin programación, sin opiniones sobre lo que deberías escribir.

Es la pieza que un agente necesita para llegar a Threads. Qué publicar es problema tuyo.

npx -y @andreaselmi/threads-mcp    # needs THREADS_ACCESS_TOKEN in the environment

• Inicio rápido

• Herramientas

• Cómo obtener un token de acceso

• Integrarlo en un cliente

• Solución de problemas

• Lo que deliberadamente no hace

• Desarrollo

Inicio rápido

Requiere Node 20 o superior. No necesitas instalar nada: los clientes MCP ejecutan el servidor con npx, que lo descarga en el primer uso.

1. Obtén un token de acceso de larga duración — guía completa a continuación. Esta es la única parte realmente engorrosa, y es culpa de Meta, no de este paquete.

2. Expórtalo en la shell desde la que inicies tu cliente MCP:

   export THREADS_ACCESS_TOKEN="THQ..."

3. Añade el servidor a la configuración MCP de tu cliente:

   {
     "mcpServers": {
       "threads": {
         "command": "npx",
         "args": ["-y", "@andreaselmi/threads-mcp"]
       }
     }
   }

4. Reinicia el cliente y pregúntale quién eres. Debería llamar a threads_whoami y responder con tu nombre de usuario.

Para comprobar que el servidor funciona antes de involucrar a un cliente:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y @andreaselmi/threads-mcp

Una línea JSON con el nombre threads-mcp significa que se inició y leyó tu token. Un mensaje de error en stderr te indica lo que falta.

Related MCP server: meta-threads-mcp

Herramientas

Las dos herramientas de publicación están marcadas con destructiveHint: true; el resto son readOnlyHint. Los clientes que piden confirmación antes de acciones destructivas la pedirán antes de estas, y con razón: una publicación sale en directo inmediatamente y la API no puede editarla ni borrarla. Eliminarla implica abrir la aplicación de Threads.

threads_post_insights lee las estadísticas solo de tus propias publicaciones y necesita el permiso threads_manage_insights. threads_publishing_limit informa de la cuota móvil de 24 horas, que es de 250 publicaciones por cuenta por defecto.

Por qué existe threads_publish_container

Publicar en Threads son dos llamadas: crear un contenedor y luego publicarlo. Si falla la segunda llamada, el contenedor sigue existiendo y sigue siendo válido durante 24 horas — reintentar la operación completa publicaría el mismo texto dos veces. Cuando falla una publicación, este servidor pone el id del contenedor en el mensaje de error; pásalo a threads_publish_container para terminar el trabajo exactamente una vez.

El servidor también espera a que un contenedor alcance FINISHED antes de publicarlo, consultando cada 2 segundos durante un minuto como máximo, de modo que un contenedor lento no se confunda con un fallo.

Cómo obtener un token de acceso

El flujo de Meta tiene cuatro pasos y no hay atajos. Reserva quince minutos la primera vez.

1. Crear la aplicación

Ve a developers.facebook.com/apps y crea una aplicación con el caso de uso Threads. El panel genera dos conjuntos de credenciales — usa el ID y secreto específicos de Threads, no los de Facebook. Esto confunde a casi todo el mundo.

2. Añadir permisos y un usuario de prueba

Dentro del caso de uso de Threads, añade los permisos que necesites:

Después añade tu cuenta de Threads como usuario de prueba, y acepta la invitación desde los ajustes de esa cuenta (Cuenta → Permisos del sitio web → Invitaciones). Hasta que se acepte la invitación, cada llamada falla con un error de permisos que nunca menciona la invitación.

3. Obtener un token de corta duración

Abre la ventana de autorización en un navegador, sustituyendo los marcadores de posición:

https://threads.net/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code

Aprueba y aterrizarás en tu redirect_uri con ?code=... añadido. La URI de redirección debe coincidir exactamente con una registrada en los ajustes de la aplicación. Copia el código — es de un solo uso y caduca en minutos — y cámbialo:

curl -X POST https://graph.threads.net/oauth/access_token \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=THE_CODE_FROM_THE_REDIRECT

Esto devuelve un token de corta duración, válido durante una hora. No te detengas aquí.

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

curl -G https://graph.threads.net/access_token \
  -d grant_type=th_exchange_token \
  -d client_secret=YOUR_APP_SECRET \
  -d access_token=THE_SHORT_LIVED_TOKEN

El resultado es válido durante 60 días. Este es el valor para THREADS_ACCESS_TOKEN.

Mantenerlo vivo

Un token de larga duración puede renovarse una vez que tenga al menos 24 horas y antes de que caduque. Cada renovación da otros 60 días:

curl -G https://graph.threads.net/refresh_access_token \
  -d grant_type=th_refresh_token \
  -d access_token=YOUR_LONG_LIVED_TOKEN

Un token que no se usa durante 60 días caduca y no puede renovarse — vuelves a empezar desde el paso 3. Pon un recordatorio en tu calendario; nada te avisa.

Integrarlo en un cliente

Variables de entorno

El token se lee del entorno al inicio y nunca se escribe en ningún sitio — ni en un archivo, ni en una línea de log. Prefiere exportarlo en tu shell en lugar de escribirlo en un archivo de configuración: los archivos de configuración acaban en el control de versiones, las exportaciones de shell no.

Claude Code

claude mcp add threads --scope user -- npx -y @andreaselmi/threads-mcp

O haz commit de un .mcp.json en la raíz de un proyecto, para que cualquiera que trabaje en él tenga el servidor:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp@^0.1.0"]
    }
  }
}

Fijar ^0.1.0 recoge las correcciones, pero no una futura versión mayor que cambie las herramientas. Comprueba la conexión con /mcp.

Claude Desktop, Cursor y otros clientes

Con la misma forma, en el archivo de configuración de ese cliente — claude_desktop_config.json para Claude Desktop, ~/.cursor/mcp.json para Cursor. Los clientes que no heredan el entorno de tu shell necesitan que se les pase el token explícitamente:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"],
      "env": { "THREADS_ACCESS_TOKEN": "THQ..." }
    }
  }
}

Si haces esto, ese archivo contiene ahora una credencial activa: mantenlo fuera del control de versiones.

Instalarlo en lugar de eso

Si prefieres no pasar por npx en cada inicio:

npm install -g @andreaselmi/threads-mcp

y luego usa "command": "threads-mcp" sin args.

Solución de problemas

El servidor no arranca / el cliente muestra CONNECTION_CLOSED. El proceso ha terminado al inicio, casi siempre porque THREADS_ACCESS_TOKEN no está definido en el entorno desde el que se lanzó el cliente. Exportarlo en una terminal no llega a una aplicación que ya está en marcha, ni a una que se haya abierto desde el Dock. Ejecuta el servidor a mano para ver el mensaje real:

npx -y @andreaselmi/threads-mcp

Imprime el motivo y termina.

Invalid OAuth access token o similar. El token ha caducado (60 días), o todavía estás usando el de corta duración del paso 3. Repite el paso 4.

Un error de permisos en una llamada que debería funcionar. O falta el permiso — estadísticas y publicación necesitan cada uno el suyo — o la invitación al usuario de prueba nunca se aceptó desde los ajustes de la cuenta de Threads.

Post is N characters, the Threads limit is 500. Lo lanza este servidor antes de enviar ninguna solicitud, así que no se ha publicado nada. Divide el texto.

Una publicación ha fallado y no estás seguro de si se ha publicado. Lee el error: si menciona un id de contenedor, el contenedor existe y la publicación no ha salido. Llama a threads_publish_container con ese id en lugar de publicar de nuevo. Si no menciona ninguno, comprueba threads_list_posts antes de reintentar.

Cuota agotada. threads_publishing_limit muestra la ventana móvil de 24 horas — 250 publicaciones por cuenta. Cuando se agota, no se publica nada hasta que las publicaciones quedan fuera de la ventana.

Lo que deliberadamente no hace

Solo publicaciones de texto — sin imágenes, vídeo, carruseles ni adjuntos de enlaces. Lee tus propias publicaciones, no las respuestas, menciones ni el contenido de nadie más. No programa, no reintenta con temporizador ni conserva estado entre llamadas: no tiene base de datos y no recuerda nada.

Tampoco sabe nada sobre qué publicas. Aquí no viven temas, tono de voz ni reglas editoriales; eso pertenece a quien lo esté llamando. A las pull requests que añadan comportamiento específico de un producto se les pedirá que lo muevan al llamador.

Desarrollo

npm install
npm test          # vitest, no network: fetch is stubbed
npm run dev       # run the server from source over stdio
npm run build     # tsc to dist/

Cada prueba se ejecuta contra un fetch simulado, así que la suite nunca toca la API real y no necesita token. Incidencias y pull requests: github.com/andreaselmi/threads-mcp.

Licencia

MIT