Skip to main content
Glama
Threads MCP

Threads MCP

by kerwilgil

Threads MCP

A controlled Model Context Protocol server for reading and publishing to a Meta Threads account through the official Threads API. Each person runs their own copy, registers their own Meta app, and connects their own Threads account. Nothing is shared between installations.

Publishing is designed for human-approved content: an agent can only publish a text or image that was explicitly registered as approved, and a publication that may have reached Meta is never replayed automatically.

Unofficial project. It is not affiliated with, endorsed by, or sponsored by Meta or Threads.

Idioma: the documentation is in English. A step-by-step installation guide in Spanish is in Guía de instalación (español).

Features

Tool

Type

Description

threads_get_profile

read

Authenticated account profile (no credentials).

threads_publish_text

write

Publish a text post (up to 500 characters). Optional topic_tag, and an optional image_url that takes the image path.

threads_publish_image

write

Publish an image post from a public HTTPS URL, with optional text and topic_tag.

threads_get_post

read

Fetch one post by its provider id, for verification.

threads_list_recent_posts

read

List recent posts (1-100), for verification.

Also included:

  • OAuth set-up from the command line (threads-mcp-auth). OAuth helpers are not MCP tools, so agents cannot change credentials.

  • Encrypted token store (Fernet). Tokens are never returned by any tool.

  • Publication ledger (SQLite). Repeating a successful call with the same idempotency key returns the recorded post instead of creating a second one.

  • Unknown-outcome handling. If Meta may have received a publish request, the result is unknown and the write is never replayed.

  • Approval gate (gate/). Only texts registered in a local registry can be published through the gate.

  • Stdio supervisor (supervisor/). Keeps the MCP host attached if the gate or the backend exits, without repeating in-flight publications.

Related MCP server: Threads Scheduler MCP

Requirements

  • Python 3.11 or newer (3.11 and 3.13 are tested in CI). On macOS, the system python3 may be older; install a newer Python with Homebrew, the python.org installer, or uv.

  • macOS or Linux. The launchers are POSIX sh scripts and the supervisor uses POSIX poll. Windows is not supported by these components, although the Python package itself does not depend on them.

  • A Meta developer app with the Threads API enabled, and a Threads account you control.

  • An MCP client that can launch a stdio server (for example Claude Desktop, Claude Code, Cursor or another MCP host).

Guía de instalación (español)

Esta guía explica cómo instalar el servidor, crear tu propia aplicación de Meta, conectar tu cuenta de Threads y configurar la aprobación de publicaciones. Todos los comandos se ejecutan en una terminal de macOS o Linux.

1. Crear tu aplicación de Meta

  1. Entra en el portal de desarrolladores de Meta y crea una aplicación con el caso de uso de la API de Threads.

  2. En la configuración del producto Threads, añade una URL de redirección (THREADS_REDIRECT_URI). Debe ser una URL HTTPS que controles. No necesita servir ninguna página: copiarás el code y el state de la barra de direcciones después de autorizar.

  3. Activa los permisos threads_basic y threads_content_publish.

  4. Si la aplicación está en modo de desarrollo, añade tu cuenta de Threads como usuario de prueba. Las políticas y nombres de permisos de Meta cambian con el tiempo: sigue siempre su documentación vigente.

  5. Anota el ID de la aplicación (THREADS_APP_ID) y el secreto de la aplicación (THREADS_APP_SECRET). El secreto nunca debe guardarse en el repositorio ni en un chat.

2. Descargar e instalar el servidor

git clone https://github.com/kerwilgil/threads-mcp-community.git
cd threads-mcp-community
python3.12 -m venv .venv          # cualquier Python 3.11 o superior (o: uv venv -p 3.12 .venv)
.venv/bin/pip install -e ".[dev]"

Instala desde el repositorio clonado, no solo desde pip: el wheel no incluye gate/ ni supervisor/, que los lanzadores usan directamente. El entorno virtual debe estar en .venv dentro de la carpeta del repositorio (o define THREADS_MCP_VENV). El lanzador lo usa para arrancar el servidor. Si python3 es anterior a 3.11, indica el intérprete correcto en THREADS_GATE_PYTHON cuando configures el cliente MCP.

3. Crear la clave de cifrado local

mkdir -p ~/.config/threads-mcp && chmod 700 ~/.config/threads-mcp
.venv/bin/threads-mcp-auth keygen > ~/.config/threads-mcp/encryption.key
chmod 600 ~/.config/threads-mcp/encryption.key

Esta clave cifra el token de Threads. Haz una copia de seguridad fuera del equipo y no la compartas. Si la pierdes, tendrás que volver a autorizar la cuenta; el registro de publicaciones no se pierde.

4. Autorizar tu cuenta de Threads

Define las variables de la aplicación (solo en esta sesión de terminal):

export THREADS_APP_ID="<ID de tu aplicación>"
export THREADS_REDIRECT_URI="<la misma URL de redirección de Meta>"
bin/threads-mcp-launcher auth auth-url

Abre la URL que aparece, autoriza la cuenta y copia los valores code y state de la URL a la que te redirige Meta. El state caduca a los 15 minutos. Después completa el intercambio:

export THREADS_APP_SECRET="<secreto de tu aplicación>"
bin/threads-mcp-launcher auth exchange --code '<code>' --state '<state>'
bin/threads-mcp-launcher auth status

auth status muestra solo metadatos no secretos (nombre de usuario, caducidad). Cuando termines, borra las variables sensibles (unset THREADS_APP_SECRET) y considera limpiar el historial del terminal si contiene el code.

5. Configurar el cliente MCP con aprobación

Configura tu cliente MCP para lanzar el supervisor, que ejecuta el gate, y no el lanzador directamente. Ejemplo con la estructura habitual mcpServers:

{
  "mcpServers": {
    "threads": {
      "command": "/ruta/absoluta/a/threads-mcp-community/bin/threads-mcp-supervised",
      "args": []
    }
  }
}

Reinicia el cliente MCP después de cambiar su configuración. Si Python 3.11+ no es el python3 del sistema, añade "env": {"THREADS_GATE_PYTHON": "/ruta/a/python3.12"}.

6. Aprobar publicaciones

Un agente solo puede publicar textos registrados como aprobados. Cuando una persona apruebe el texto exacto:

printf '%s' "<texto exacto aprobado>" > ./aprobado.txt
python3 gate/threads_publication_gate.py register \
    --key demo-2026-01-15-mi-publicacion-v1 --text-file ./aprobado.txt \
    --label "Mi publicación" --approved-by "yo, 2026-01-15"
rm -f ./aprobado.txt
python3 gate/threads_publication_gate.py list

El agente debe usar el mismo texto y el mismo publication_ref. Cualquier cambio, incluso un espacio, exige una nueva aprobación con una nueva clave. Las imágenes y etiquetas se aprueban con --image-url y --topic-tag; consulta docs/images-and-topic-tags.md.

7. Comprobar que funciona

Pide al cliente MCP que llame a threads_get_profile y a threads_list_recent_posts. Después, registra un texto de prueba y publícalo solo si lo has aprobado explícitamente. Si un resultado es unknown, no vuelvas a publicar: revisa primero la cuenta en la aplicación de Threads.

Quick start (English)

git clone https://github.com/kerwilgil/threads-mcp-community.git && cd threads-mcp-community
python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"
mkdir -p ~/.config/threads-mcp && chmod 700 ~/.config/threads-mcp
.venv/bin/threads-mcp-auth keygen > ~/.config/threads-mcp/encryption.key && chmod 600 ~/.config/threads-mcp/encryption.key
# Then authorize the account (section "Connect a Threads account") and point your MCP host at bin/threads-mcp-supervised.

Connect a Threads account

The OAuth flow is the same as the Spanish guide above:

  1. Create a Meta app with the Threads API, a redirect URI and the scopes threads_basic and threads_content_publish.

  2. Set THREADS_APP_ID and THREADS_REDIRECT_URI, then run bin/threads-mcp-launcher auth auth-url and open the URL.

  3. Copy code and state from the redirect address (the state expires after 15 minutes).

  4. Set THREADS_APP_SECRET and run bin/threads-mcp-launcher auth exchange --code '<code>' --state '<state>'.

  5. Verify with bin/threads-mcp-launcher auth status.

The OAuth commands are CLI-only and are never exposed as MCP tools.

Using the tools

Read examples (no approval needed):

{"name": "threads_get_profile", "arguments": {}}
{"name": "threads_list_recent_posts", "arguments": {"limit": 5}}
{"name": "threads_get_post", "arguments": {"post_id": "<post id>"}}

Publishing through the approval gate (the host shows publication_ref instead of idempotency_key):

{"name": "threads_publish_text",
 "arguments": {"text": "<exact approved text>", "publication_ref": "demo-2026-01-15-launch-post-v1"}}
{"name": "threads_publish_image",
 "arguments": {"text": "<exact approved text>", "image_url": "https://example.com/images/demo.jpg",
               "publication_ref": "demo-2026-02-01-image-post-v1", "topic_tag": "ExampleTopic"}}

A publish result has one of three statuses:

Status

Meaning

What to do

published

Meta returned a post id. The result includes post_id and, when available, permalink.

Nothing. Repeating the call returns the same post.

failed

Nothing was published. Either the failure was definitive, or it happened before any public write.

Read the message. Retrying with the same key is safe: the ledger either makes a new attempt or returns the same failure.

unknown

Meta may have published the post.

Do not retry. Check the account in the Threads app or with threads_list_recent_posts.

Without the gate (bin/threads-mcp-launcher directly), threads_publish_text takes an idempotency_key and no approval check is performed. Do not expose that configuration to an agent.

Configuration

Copy .env.example only for local experiments; the launchers do not read .env. The variables are:

Variable

Required

Purpose

TOKEN_ENCRYPTION_KEY

yes (set by the launcher)

Fernet key for the token store. Read from ~/.config/threads-mcp/encryption.key by the launcher.

THREADS_APP_ID, THREADS_REDIRECT_URI

OAuth only

Meta app and redirect URI.

THREADS_APP_SECRET

OAuth exchange only

Meta app secret. Never store it in a file under version control.

THREADS_API_BASE

no

Must be https://graph.threads.net/vX.Y. Default https://graph.threads.net/v1.0.

THREADS_REQUEST_TIMEOUT

no

Seconds per request. Default 15.

THREADS_TOKEN_STORE, THREADS_LEDGER_PATH, THREADS_OAUTH_STATE_PATH

no

Overrides. The launcher sets them from the XDG directories.

THREADS_GATE_REGISTRY, THREADS_GATE_PYTHON

no

Gate registry path and Python interpreter for the wrapper scripts.

THREADS_MCP_RUNTIME, THREADS_MCP_VENV

no

Launcher layout overrides.

Local files (default XDG locations):

File

Purpose

~/.config/threads-mcp/encryption.key

Encryption key (mode 600).

~/.config/threads-mcp/token.enc

Encrypted Threads token.

~/.config/threads-mcp/approved-publications.json

Approval registry (mode 600).

~/.local/state/threads-mcp/publications.sqlite3

Publication ledger. Keep it; it prevents duplicates.

~/.local/state/threads-mcp/gate-verifications.ndjson

Verification log written by the gate.

Security

  • Tokens are encrypted at rest and are never returned by tools, logged, or placed in error messages.

  • The encryption key and the token store are separate files. Anyone who can read both can use the token: protect them with operating-system permissions and back up the key securely.

  • Provider response bodies are not returned to the model. Errors carry only fixed messages and shape-checked diagnostics.

  • Each installation has its own key, token, ledger and registry. Nothing is shared with other people or with this repository.

  • The gate fails closed: unregistered text, a changed byte, a wrong reference, or a missing registry blocks publication.

  • Publication uses only the official HTTPS Graph API. Browser automation is not used.

See SECURITY.md for how to report a vulnerability and docs/architecture.md for the full publication model.

Limitations

  • Text posts are limited to 500 characters. Image posts need a public HTTPS URL that Meta can fetch.

  • Image processing is asynchronous. If the container is not FINISHED after about 45 seconds, the result is a retryable failed with the same reference.

  • Not implemented in this release: replies, moderation, insights, video, carousels, and deleting posts.

  • Access tokens expire. Long-lived tokens are refreshed automatically when they are within 3 days of expiry; if a token has already expired, run the OAuth flow again.

  • Meta's rate limits and app-review rules apply. A rate-limit response on a publish request produces unknown.

  • A recent feed match of the same text does not prove that a specific attempt published.

Troubleshooting

Symptom

Likely cause and fix

missing executable .../.venv/bin/threads-mcp

Install the package into .venv (step 2), or set THREADS_MCP_VENV.

ModuleNotFoundError: threads_mcp

The virtualenv lost the package. Run .venv/bin/pip install -e . again.

missing .../encryption.key

Create the key with threads-mcp-auth keygen (step 3).

Threads tool failed. Check local authentication, input, and publication state.

Usually no token or an expired token: complete the OAuth flow, then run auth status.

The stored Threads credential cannot be decrypted

The key file does not match the token store. Restore the original key or authorize again.

approved-publications registry not found

Register the approved text first (step 6).

This exact text is not in the approved-publications registry

The text differs from the registered text by at least one byte. Re-register the exact text with a new key.

publication_ref does not match

Use the key shown by list, unchanged.

… takes exactly … (no idempotency_key)

The host is still calling with the old schema. Restart the MCP host so it reloads the tool list.

ImportError: cannot import name 'UTC' from the gate

The python3 on your PATH is older than 3.11. Set THREADS_GATE_PYTHON to a 3.11+ interpreter.

Host shows MCP server exited

Restart the host. Check that bin/threads-mcp-supervised is executable and that its path is absolute.

Result unknown

Do not retry. Check the account in the Threads app first.

Updating

cd threads-mcp-community
git pull
.venv/bin/pip install -e ".[dev]"

Then restart the MCP host. Keep the ledger and the registry when updating. Stop any older server process before you upgrade, because older versions do not share the owner checks of newer ones.

Development

python3.12 -m venv .venv && .venv/bin/pip install -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/pytest
.venv/bin/python -m compileall -q src tests gate supervisor

The test suite uses synthetic credentials and texts, blocks live HTTP, and never publishes. Tests cover the tool surface over stdio, OAuth against a mocked provider, encryption, duplicate prevention, concurrency, provider errors, image publication, the gate, and the supervisor. Contributions are welcome; see CONTRIBUTING.md.

Project layout

src/threads_mcp/        MCP server, OAuth, token store, ledger, Graph client
bin/                    stdio launcher and supervised entry point
gate/                   approval gate (registry, verification, tests with a mock backend)
supervisor/             stdio supervisor that restarts children without replaying work
docs/                   architecture, supervisor and image/topic-tag documentation
tests/                  unit, integration and stdio tests

License

MIT. Copyright (c) 2026 kerwilgil.

Available Tools

5 tools
threads_get_postGet Threads postB
Read-onlyIdempotent

Fetch one Threads post by provider post id for verification.

Inputs: post_id (required). Returns: id, text, media_url, permalink, +3 more

threads_get_profileGet Threads profileA
Read-onlyIdempotent

Read the authenticated Threads profile.

Inputs: no named parameters. Returns: id, name, username, biography, +1 more

threads_list_recent_postsList recent Threads postsB
Read-onlyIdempotent

List recent Threads posts for verification and duplicate detection.

Inputs: limit. Returns: result

threads_publish_imagePublish Threads imageA
Idempotent

Publish one approved image post (text + public HTTPS image_url, optional topic_tag of 1-50 characters without '.' or '&') to Threads. idempotency_key must remain stable for retries of the same logical publication. The media container is published only after Threads reports it FINISHED. The tool prevents blind retries when provider outcome is unknown.

Inputs: text (required), image_url (required), idempotency_key (required), topic_tag. Returns: status, message, post_id, permalink, +2 more

threads_publish_textPublish Threads textA
Idempotent

Publish one approved text post to Threads. idempotency_key must remain stable for retries of the same logical publication. Optional topic_tag (1-50 characters without '.' or '&'). Optional image_url (public HTTPS) turns the call into an image post, exactly like threads_publish_image. The tool prevents blind retries when provider outcome is unknown.

Inputs: text (required), idempotency_key (required), image_url, topic_tag. Returns: status, message, post_id, permalink, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 5 tools

    Disambiguation4/5

    Read tools (get_profile, get_post, list_recent_posts) and write tools are clearly separated by resource and action. The one blur is threads_publish_text vs threads_publish_image: publish_text explicitly becomes an image post when image_url is supplied, 'exactly like threads_publish_image', so an agent may be unsure which to call for image content.

    Naming Consistency5/5

    Every tool uses the same threads_ prefix followed by a snake_case verb_noun pattern (get_profile, get_post, publish_text, publish_image, list_recent_posts). No mixing of conventions or vague verbs.

    Tool Count5/5

    Five tools is well within the well-scoped range and each earns its place: two read/verification tools, two publish paths, and a recent-posts listing for duplicate detection. Nothing redundant or missing at the count level.

    Completeness3/5

    Core lifecycle of publish plus verify is covered, including idempotency and duplicate detection. However, there is no delete/retract, no reply or quote/repost capability, and no post-level insights/metrics, which are notable gaps for a Threads publishing surface.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      C
      maintenance
      Enables posting and managing Threads content via Meta Threads API, including text, image, video, carousel, and replies.
      9
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to manage a Threads profile through Meta's API, including posting, threads, replies, reply moderation, and insights.
      30
      30 npm
      4
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      This server enables local access to official Meta Threads data, including latest posts, analytics insights, follower demographics, and guarded, approval-based publishing of posts and replies.
      6
      MIT