Threads MCP
Integrates with the official Threads API to read the authenticated account profile and recent posts, fetch individual posts, and publish approved text or image posts with optional topic tags and idempotent publication tracking.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Threads MCP publish the approved text post about tomorrow's event"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| read | Authenticated account profile (no credentials). |
| write | Publish a text post (up to 500 characters). Optional |
| write | Publish an image post from a public HTTPS URL, with optional text and |
| read | Fetch one post by its provider id, for verification. |
| 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
unknownand 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
python3may be older; install a newer Python with Homebrew, the python.org installer, oruv.macOS or Linux. The launchers are POSIX
shscripts and the supervisor uses POSIXpoll. 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
Entra en el portal de desarrolladores de Meta y crea una aplicación con el caso de uso de la API de Threads.
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 elcodey elstatede la barra de direcciones después de autorizar.Activa los permisos
threads_basicythreads_content_publish.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.
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.keyEsta 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-urlAbre 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 statusauth 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 listEl 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:
Create a Meta app with the Threads API, a redirect URI and the scopes
threads_basicandthreads_content_publish.Set
THREADS_APP_IDandTHREADS_REDIRECT_URI, then runbin/threads-mcp-launcher auth auth-urland open the URL.Copy
codeandstatefrom the redirect address (the state expires after 15 minutes).Set
THREADS_APP_SECRETand runbin/threads-mcp-launcher auth exchange --code '<code>' --state '<state>'.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 |
| Meta returned a post id. The result includes | Nothing. Repeating the call returns the same post. |
| 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. |
| Meta may have published the post. | Do not retry. Check the account in the Threads app or with |
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 |
| yes (set by the launcher) | Fernet key for the token store. Read from |
| OAuth only | Meta app and redirect URI. |
| OAuth exchange only | Meta app secret. Never store it in a file under version control. |
| no | Must be |
| no | Seconds per request. Default |
| no | Overrides. The launcher sets them from the XDG directories. |
| no | Gate registry path and Python interpreter for the wrapper scripts. |
| no | Launcher layout overrides. |
Local files (default XDG locations):
File | Purpose |
| Encryption key (mode |
| Encrypted Threads token. |
| Approval registry (mode |
| Publication ledger. Keep it; it prevents duplicates. |
| 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
FINISHEDafter about 45 seconds, the result is a retryablefailedwith 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 |
| Install the package into |
| The virtualenv lost the package. Run |
| Create the key with |
| Usually no token or an expired token: complete the OAuth flow, then run |
| The key file does not match the token store. Restore the original key or authorize again. |
| Register the approved text first (step 6). |
| The text differs from the registered text by at least one byte. Re-register the exact text with a new key. |
| Use the key shown by |
| The host is still calling with the old schema. Restart the MCP host so it reloads the tool list. |
| The |
Host shows | Restart the host. Check that |
Result | 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 supervisorThe 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 testsLicense
MIT. Copyright (c) 2026 kerwilgil.
Available Tools
5 toolsthreads_get_postGet Threads postBRead-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 profileARead-onlyIdempotent
Read the authenticated Threads profile.
Inputs: no named parameters. Returns: id, name, username, biography, +1 more
threads_list_recent_postsList recent Threads postsBRead-onlyIdempotent
List recent Threads posts for verification and duplicate detection.
Inputs: limit. Returns: result
threads_publish_imagePublish Threads imageAIdempotent
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 textAIdempotent
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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Publish, reply, moderate, search and read insights on your Threads (threads.com) account.
Publish and schedule Threads posts from your AI assistant.
Threads scheduler for AI agents: write, schedule and publish posts, review replies, read insights.
Publish and schedule Bluesky posts and threads from your AI assistant.
Related MCP Servers
- FlicenseBqualityCmaintenanceEnables posting and managing Threads content via Meta Threads API, including text, image, video, carousel, and replies.9-
- FlicenseNot gradedqualityDmaintenanceA local-first MCP server for reading, planning, scheduling, and publishing Meta Threads posts, with OAuth and Keychain integration.-
- AlicenseAqualityBmaintenanceEnables AI agents to manage a Threads profile through Meta's API, including posting, threads, replies, reply moderation, and insights.3030 npm4MIT
- AlicenseBqualityCmaintenanceThis 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.6MIT