Threads Server

threads-mcp is a stdio MCP server for the official Threads API. It is designed to stay close to the published Meta Threads documentation while exposing a practical MCP tool surface for auth, publishing, reading, moderation, insights, discovery, locations, and setup diagnostics.

The current build is intentionally limited to officially documented Threads capabilities and the official Postman collection. It does not rely on undocumented fallback endpoints or convenience wrappers that would be difficult to maintain in a public package.

Highlights

• Official Threads API scope only
• MCP tools for auth, profile lookup, publishing, reading, replies, insights, search, locations, oEmbed, and diagnostics
• Publish inputs modeled in camelCase and serialized internally to the snake_case parameters expected by Threads
• Multi-step carousel publishing support
• Shared client layer for retries, polling, pagination, and normalized Meta API errors

Quick start

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Create your local environment file and set at least THREADS_ACCESS_TOKEN.

4. If you still need a token, run the local OAuth helper:

npm run auth:token

5. Start the server:

node dist/index.js

6. Call validate_setup before using publish or moderation flows against a real account.

Tool catalog

Auth

• exchange_code_for_token
• get_long_lived_access_token
• refresh_access_token
• get_app_access_token

Profiles and discovery

• get_me
• get_profile
• get_profile_threads

Publishing and lifecycle

• get_publishing_limit
• create_thread_container
• publish_thread
• create_and_publish_thread
• repost_thread
• delete_thread

Reading and replies

• get_threads
• get_thread
• get_replies
• get_thread_conversation
• get_pending_replies
• manage_reply
• manage_pending_reply

Insights, search, and embeds

• get_user_insights
• get_thread_insights
• search_threads
• get_mentions
• get_oembed

Locations and diagnostics

• search_locations
• get_location
• validate_setup

Explicitly out of scope for v1

• Webhooks
• Embedded OAuth callback hosting
• Any undocumented fallback endpoints or convenience features that are not covered by the official docs or official Postman collection

Architecture

The server is split into a few clear layers:

• src/index.ts bootstraps the MCP stdio transport.
• src/threads/client.ts owns authenticated HTTP calls, retries, pagination, polling, and normalized Meta API errors.
• src/tools/ contains one module per tool family plus shared schemas.

The publish input model is exposed as a single public discriminated union covering text, image, video, carousel, and reply.

Prerequisites

You need all of the following before the server can make live API calls:

• A Meta app configured for the Threads use case
• A Threads user access token for the account you want to operate on
• Advanced access and app review where your integration requires it
• Node.js 20+ on the machine where the server will run

Environment variables

Required for most user-token tools:

• THREADS_ACCESS_TOKEN

Optional:

• 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

Copy .env.example and set at least the access token. THREADS_APP_ID and THREADS_APP_SECRET are also needed for the auth helper tools and for get_oembed when you do not pass an explicit app access token.

Where to get THREADS_APP_ID

• Open your app in the Meta for Developers dashboard: https://developers.facebook.com/apps/
• Open the app created with the Threads use case
• Go to Use Cases -> Threads -> Customize -> Settings
• Copy the Threads App ID from that page
• Use that value as THREADS_APP_ID

Important:

• Do not use the general Meta app ID from the top-level app dashboard or settings page
• Use the Threads use-case-specific credentials from Use Cases -> Threads -> Customize -> Settings

THREADS_APP_SECRET comes from the same Threads use-case settings page. Keep it private.

Token helper script

The repository includes a local OAuth helper that follows the Meta Threads access-token flow:

1. Open the Threads authorization window
2. Receive the authorization code on a local callback URL
3. Exchange it for a short-lived token
4. Exchange that for a long-lived token
5. Save the result into .env as THREADS_ACCESS_TOKEN

Setup:

• Add your Meta app credentials to .env
• Make sure your app's valid OAuth redirect URI matches THREADS_REDIRECT_URI

Run:

npm run auth:token

Optional flags:

• --redirect-uri http://127.0.0.1:8788/callback
• --env-file .env.local
• --no-open

Required scopes by tool family

• threads_basic Used by get_me, get_profile, get_threads, get_thread, and baseline setup validation.
• threads_content_publish Used by get_publishing_limit, create_thread_container, publish_thread, and create_and_publish_thread.
• threads_read_replies Used by get_replies and safe reply-read probes in validate_setup.
• threads_manage_replies Used by manage_reply.
• threads_manage_insights Used by get_user_insights and get_thread_insights.
• threads_keyword_search Used by search_threads.
• threads_profile_discovery Used by get_profile and get_profile_threads for public account discovery scenarios.
• threads_location_tagging Used by search_locations, get_location, and publish flows that set locationId.
• threads_delete Used by delete_thread.

validate_setup performs safe probes to infer access for threads_basic, threads_content_publish, threads_read_replies, threads_manage_insights, threads_keyword_search, threads_profile_discovery, and threads_location_tagging. It deliberately does not perform destructive probes for threads_manage_replies or threads_delete, so those scopes are not actively validated by setup.

Publish behavior

The server models official container options in camelCase and serializes them internally to the snake_case parameters expected by the Threads API.

Supported inputs include:

• Common fields: text, replyControl, replyToId, quotePostId, topicTag, locationId, textEntities, allowlistedCountryCodes
• Text-only fields: linkAttachment, pollAttachment, textAttachment, gifAttachment, enableReplyApprovals, autoPublishText, isGhostPost
• Image or video fields: imageUrl, videoUrl, altText, isSpoilerMedia
• Carousel items: validated arrays of image or video items with per-item media fields

Carousel publishing follows the official multi-step flow:

1. Create one item container per image or video with is_carousel_item=true
2. Create the parent carousel container with children=[...]
3. Publish the parent container

Coverage notes

The repository currently covers these official Threads API families:

• Authorization helpers
• Publishing, including quote posts, repost publishing, and container status polling
• User profile lookup and public profile post retrieval
• Threads media retrieval
• Reply retrieval, flattened conversations, pending replies, hide and unhide, and approve and ignore flows
• User and post insights
• Keyword search and mentions
• Location search and location retrieval
• oEmbed
• Setup diagnostics

Local MCP config example

Example Claude Desktop style config:

{
  "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"
      }
    }
  }
}

If you later publish this package as a CLI, the command can become threads-mcp.

Publishing

The package metadata is already configured for npm publication as a public package:

• package name: threads-mcp
• current version: 0.0.0
• CLI entrypoint: threads-mcp
• publish access: public

Before publishing, run:

npm run build
npm test
npm publish --access public

prepublishOnly is configured to run the build and test steps automatically during npm publish.

Development

Install dependencies once Node.js is available:

npm install
npm run build
npm test

Suggested manual checks:

1. Run npm run build to verify TypeScript compilation.
2. Run npm test to execute the schema, client, and tool registration tests.
3. Start the server with node dist/index.js.
4. Call validate_setup first with a real token.
5. Exercise create_thread_container and publish_thread against a test Threads account.

Known limitations

• Transport is stdio only in v1
• There is no embedded OAuth callback server; token exchange helpers are exposed as MCP tools instead
• validate_setup cannot safely verify threads_manage_replies without performing a state-changing moderation call
• validate_setup also does not perform a state-changing delete probe
• create_and_publish_thread intentionally rejects autoPublishText=true because that flag conflicts with the tool's explicit two-step contract
• Reply publishing is modeled as a dedicated reply variant backed by the official reply_to_id parameter and currently targets text replies in the public schema
• Verification of live API behavior still depends on valid app credentials, approved scopes, and a real Threads account

Sources used for API scope and endpoint selection

• Meta Threads API reference: https://developers.facebook.com/docs/threads/reference
• Meta Threads publishing reference: https://developers.facebook.com/docs/threads/reference/publishing
• Meta official Postman workspace: https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api