Threads MCP Server

An MCP server for the official Meta Threads API. Let Claude (or any MCP client) publish posts, carousels, polls, replies and quotes, read your posts, replies, mentions and insights, search public posts, and schedule posts — using only endpoints Meta documents.

• Built on the MCP TypeScript SDK v2 (@modelcontextprotocol/server), works with clients on protocol 2024-11-05 through 2025-11-25
• 42 tools, each annotated as read-only or write so clients can auto-approve reads and confirm writes
• Waits for media processing before publishing, retries transient errors, and validates posts before anything goes live
• Optional read-only mode, and no token required just to start the server and list tools

v6 is a rewrite. Tools that called endpoints the Threads API does not have (likes, follows, blocks, follower lists, trending) were removed, and several were renamed or merged. See Migrating from v5.

Quick start

1. Get an access token

1. Create an app at developers.facebook.com and add the Threads API use case.
2. Add yourself as a Threads tester and accept the invite in Threads (Settings → Account → Website permissions).
3. Request the scopes you need (see Permissions); threads_basic and threads_content_publish cover posting.
4. Generate a user token, then turn it into a long-lived token (60 days). You can do the exchange from the server with exchange_for_long_lived_token if you set THREADS_APP_SECRET.

A Threads profile no longer needs a linked Instagram account, except for follower counts and demographics.

2. Add the server to your client

Claude Code

claude mcp add threads --env THREADS_ACCESS_TOKEN=your_token -- npx -y threads-mcp-server

Claude Desktop (claude_desktop_config.json) and other clients that use the same format:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "threads-mcp-server"],
      "env": {
        "THREADS_ACCESS_TOKEN": "your_long_lived_token"
      }
    }
  }
}

Requires Node.js 20 or newer.

3. Check the setup

Ask the assistant to run validate_setup. It confirms the token works, shows when it expires, and lists missing scopes together with the tools they unlock.

Configuration

Configuration is read only from the environment your MCP client passes in. A .env file in the working directory is intentionally ignored, because clients often launch servers inside projects you may not trust.

Tools

Account

Publishing

Video and image processing can take a while. Each publish call waits up to 45 seconds in total (so it finishes before typical MCP client timeouts) and sends progress notifications while it waits. If media is still processing after that, it returns the pending container_id instead of failing, and publish_container finishes the job; a thread chain returns the parts it published and where to resume. Cancelling a request stops it before anything further is published.

Scheduling

The Threads API has no native scheduling, so schedule_post saves the post locally and this server publishes it at the requested time. The server has to be running then; anything overdue is published as soon as it starts. Media containers are created at publish time, since they expire after 24 hours.

Reading

Replies

Insights

Search and locations

Permissions

Until Meta approves an advanced permission, some tools only see your own or your testers’ data — for example, search returns only your posts and profile lookup works only for official Meta accounts.

What the Threads API can’t do

There are no endpoints for liking, following, blocking, listing followers, listing likers, trending feeds, direct messages, editing posts, uploading files (media must be public URLs) or undoing a repost. This server doesn’t pretend otherwise. For following, create_web_intent_link gives you a link to click.

Migrating from v5

Development

npm install
npm run typecheck
npm test          # unit and tool tests against a mocked Threads API, no token needed
npm run build
npm run dev       # run from source with tsx

The code is split into src/threads (HTTP client, publishing flow, errors) and src/tools (one module per tool group). See CONTRIBUTING.md.

License

MIT