Threads MCP Server

A Model Context Protocol server for the Meta Threads API. Gives Claude (or any MCP client) full read/write access to Threads — post analytics, content publishing, thread chaining, webhook events, and dual-account management.

Built for use with ideAI as a cross-platform content strategy tool, but works standalone with any MCP-compatible client.

Features

• 15 MCP tools covering the full Threads API surface
• Dual account support — manage a primary and mirror/brand account from one server
• Thread chaining — publish multi-post threads with a single tool call
• Webhook events — real-time mentions, replies, and post notifications via ngrok
• Polling — detect new posts since last check for cross-account workflows
• Daily digest — aggregated insights for both accounts in one call
• Batch insights — engagement metrics across your recent posts

Tools

Tool	Description
threads_list_accounts	List configured accounts
threads_get_profile	Profile info (username, bio, verification)
threads_get_posts	Recent posts with text, media, timestamps
threads_get_post_insights	Single post metrics: views, likes, replies, reposts, quotes
threads_batch_insights	Bulk engagement metrics for N recent posts
threads_get_account_insights	Account-level metrics over day/week/28 days
threads_get_replies	Replies to a specific post
threads_get_my_replies	Your replies to other posts
threads_create_post	Publish text, image, or video posts
threads_create_thread	Publish a reply chain (thread) from an array of texts
threads_publishing_limit	Check remaining publishing quota (250/24h)
threads_get_events	Read webhook events (mentions, replies)
threads_setup_webhooks	Register webhook subscriptions with Meta
threads_poll_account	Fetch only new posts since last poll
threads_daily_digest	Full digest: insights, top posts, events, quota

All tools that interact with an account accept an optional account parameter ("primary" or "mirror", defaults to "primary").

Quick Start

1. Prerequisites

• Node.js 20+
• A Meta Developer App with Threads API enabled
• ngrok (free tier works) for OAuth callback and webhooks

2. Install

git clone https://github.com/svetimfm/threads-mcp-server.git
cd threads-mcp-server
npm install

3. Configure

cp .env.example .env

Edit .env with your Meta app credentials:

THREADS_APP_ID=your_app_id
THREADS_APP_SECRET=your_app_secret
THREADS_REDIRECT_URI=https://your-domain.ngrok-free.app/callback

4. Authenticate

Start ngrok pointing at port 3001:

ngrok http 3001 --domain=your-domain.ngrok-free.app

Then authenticate your primary account:

npm run auth:primary

This opens your browser for OAuth, exchanges for a long-lived token (60 days), and saves it to .env.

For a second account:

npm run auth:mirror

5. Build

npm run build

6. Connect to Claude

Claude Code — add to ~/.claude.json:

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/path/to/threads-mcp-server/dist/index.js"]
    }
  }
}

Claude Desktop / Cowork — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/path/to/threads-mcp-server/dist/index.js"]
    }
  }
}

7. Webhooks (optional)

For real-time event monitoring, point ngrok at port 3002:

ngrok http 3002 --domain=your-domain.ngrok-free.app

Then use the threads_setup_webhooks tool from Claude to register with Meta.

Architecture

src/
├── index.ts            # MCP server — 15 tool registrations, stdio transport
├── threads-api.ts      # Threads API client (all HTTP calls)
├── accounts.ts         # Dual account config loader + API factory
├── auth.ts             # OAuth flow (short-lived → long-lived token)
├── state.ts            # Persistent state (~/.threads-mcp-state.json)
└── webhook-server.ts   # HTTP server for Meta webhook events (port 3002)

The server runs two transports simultaneously:

• stdio for MCP communication with Claude
• HTTP on port 3002 for Meta webhook delivery (gracefully skipped if port is busy)

Scopes

The OAuth flow requests these Threads API scopes:

• threads_basic — profile access
• threads_content_publish — post creation
• threads_manage_insights — analytics
• threads_read_replies — read replies
• threads_manage_replies — manage replies
• threads_manage_mentions — mention monitoring
• threads_keyword_search — keyword search

Use Cases

• Content strategy — pull engagement data, identify what performs, plan content
• Dual-account workflows — primary posts, mirror account reacts/amplifies
• Scheduled digests — daily summary via Cowork's scheduler or cron
• Thread publishing — draft multi-part threads in conversation, publish in one call
• Engagement monitoring — webhooks for real-time mention/reply alerts

ideAI Integration

This server is designed to work alongside the ideAI MCP connector. When both are connected to Claude, you can cross-reference your Threads engagement with your personal knowledge graph, notes, and behavioral data to build data-driven content strategies grounded in your actual thinking.

License

MIT