threads-mcp

threads-mcp

A Model Context Protocol (MCP) server for the Threads API. Exposes 26 tools covering profile management, content reading, publishing, replies, and discovery.

Quick Start

1. Get a Threads Access Token

You can start using Threads API immediately for your own account via the Threads Tester — no App Review required for self-use.

1. Go to developers.facebook.com/tools/explorer
2. Select your Threads App from the app dropdown (or create one at developers.facebook.com/apps with the Threads product)
3. In the Threads Tester, generate a short-lived token
4. To get a long-lived token (60 days), call:

curl "https://graph.threads.net/access_token?grant_type=th_exchange_token&client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&access_token=SHORT_LIVED_TOKEN"

5. To refresh a long-lived token before it expires:

curl "https://graph.threads.net/refresh_access_token?grant_type=th_refresh_token&access_token=LONG_LIVED_TOKEN"

Note: Long-lived tokens expire after 60 days. Refresh them at least once per 60 days. There is no refresh token — you must always refresh before expiry.

2. Set Environment Variables

export THREADS_ACCESS_TOKEN=your_access_token_here

# Optional: skip the GET /me call at startup by providing your user ID directly
export THREADS_USER_ID=your_threads_user_id

3. Run the Server

# Install globally
npm install -g threads-mcp

# Or run directly
npx threads-mcp

Or build from source:

git clone https://github.com/your-repo/threads-mcp
cd threads-mcp
pnpm install
pnpm build
THREADS_ACCESS_TOKEN=your_token node dist/index.js

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

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

Or if installed globally:

{
  "mcpServers": {
    "threads": {
      "command": "threads-mcp",
      "env": {
        "THREADS_ACCESS_TOKEN": "your_access_token_here",
        "THREADS_USER_ID": "your_user_id_optional"
      }
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json in your project root, or ~/.cursor/mcp.json globally:

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

Tools Reference

Profile Tools

Content Tools

Publishing Tools

Replies Tools

Discovery Tools

⚠️ App Review required for threads_keyword_search and threads_profile_discovery. These permissions require Meta's App Review process before they can be used in production. For self-use development, you may be able to use them in Development mode with your own account only.

Publishing Workflow

Text Post (simplest)

Tool: create_text_post
  text: "Hello, Threads!"
  publish: true   ← publishes immediately

Video Post (requires polling)

1. Tool: create_video_post
   video_url: "https://..."
   publish: false  ← don't auto-publish; get container ID

2. Tool: get_container_status
   container_id: "from step 1"
   → poll until status = FINISHED

3. Tool: publish_thread
   container_id: "from step 1"

Carousel Post

1. Tool: create_carousel_post
   items: [{type: IMAGE, url: "..."}, {type: IMAGE, url: "..."}]
   publish: true  ← auto-publish carousel

Rate Limits

• Publishing: 250 posts per 24 hours (use get_publishing_limit to check)
• API rate limits: Follow standard Meta API rate limits (~200 calls/hour per user for most endpoints)
• Video processing: Videos typically take 10–30 seconds; poll with get_container_status

Security

• The THREADS_ACCESS_TOKEN is never logged or included in tool responses
• All outgoing URLs with the token are built internally and never surfaced to the MCP layer
• Error messages from the API that may reference the token URL are automatically redacted

Development

pnpm install
pnpm test           # run all tests
pnpm test:watch     # watch mode
pnpm typecheck      # TypeScript check
pnpm build          # build dist/

Running locally

THREADS_ACCESS_TOKEN=your_token pnpm build && node dist/index.js

Verify tool count

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' \
  | THREADS_ACCESS_TOKEN=test node dist/index.js 2>/dev/null \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(len(d['result']['tools']), 'tools')"