Threads MCP Server

A powerful Model Context Protocol (MCP) server for integrating with the Threads.com API. This server provides comprehensive tools for creating, reading, and managing Threads content programmatically.

🌐 Visit the Website for a better reading experience!

Features

• 🚀 Complete Threads API Integration - Full support for Threads.com API v1.0
• 🔧 MCP Protocol - Standard Model Context Protocol implementation
• 📊 Analytics & Insights - Access engagement metrics and analytics
• 💬 Conversation Management - Create threads, replies, and manage conversations
• 🎯 Type-Safe - Full TypeScript support with Zod schema validation
• ⚡ Rate Limiting - Token bucket algorithm to prevent API rate limit violations
• 💾 Caching Layer - In-memory caching with TTL and LRU eviction
• 🔔 Webhook Support - Event-based webhooks with automatic retries and signature verification
• ✅ Well Tested - >90% test coverage with Vitest
• 🔄 Modern Stack - Built with latest npm packages and best practices

Available Tools

The server provides the following MCP tools:

Profile & Content Management

• threads_get_profile - Get authenticated user's profile information
• threads_get_threads - Retrieve user's threads (posts) with pagination
• threads_get_thread - Get a specific thread by ID
• threads_create_thread - Create new threads with text, images, or videos
• threads_reply_to_thread - Reply to existing threads

Engagement & Analytics

• threads_get_insights - Get analytics for threads or user account
• threads_get_replies - Retrieve replies to a specific thread
• threads_get_conversation - Get full conversation threads

Prerequisites

Before you begin, you'll need:

1. Node.js 18+ - Download here
2. pnpm - Install with npm install -g pnpm
3. Meta Developer Account - Sign up here
4. Threads Account - Your personal Threads account
5. OAuth 2.0 Credentials - See OAuth Setup Guide

Getting Your Threads API Credentials

⚠️ Important: Threads uses OAuth 2.0 authentication. You cannot use simple API keys.

Quick Setup (Automatic OAuth)

1. Create a Meta App

   • Visit Meta for Developers
   • Create a new app and add the Threads API product
   • Add OAuth redirect URI: http://localhost:48810/callback
   • Get your App ID and App Secret

2. Configure Claude Desktop

   • Add to your Claude Desktop config with just your App ID and Secret
   • The server will automatically handle OAuth on first run
   • A browser will open for you to authorize the app
   • Tokens are stored and automatically refreshed!

That's it! No manual OAuth flow needed. 🎉

📖 For detailed instructions, see the OAuth Setup Guide

Installation

From npm (when published)

pnpm install -g threads-mcp

From Source

# Clone the repository
git clone https://github.com/PegasusHeavyIndustries/threads-mcp.git
cd threads-mcp

# Install dependencies
pnpm install

# Build the project
pnpm run build

Configuration

Automatic OAuth (Recommended)

The simplest way is to let the server handle OAuth automatically:

For Claude Desktop, edit your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@pegasusheavy/threads-mcp"],
      "env": {
        "THREADS_APP_ID": "your-app-id",
        "THREADS_APP_SECRET": "your-app-secret"
      }
    }
  }
}

When you start Claude Desktop:

1. A browser will automatically open
2. Log in and authorize the app
3. Done! Tokens are stored and auto-refreshed

Manual Token (Legacy)

If you prefer to use pre-generated tokens:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@pegasusheavy/threads-mcp"],
      "env": {
        "THREADS_ACCESS_TOKEN": "your-long-lived-token",
        "THREADS_USER_ID": "your-user-id"
      }
    }
  }
}

See OAuth Setup Guide for manual OAuth flow instructions.

Usage

Running the Server

# If installed globally
threads-mcp

# If running from source
pnpm run dev

Using with MCP Clients

Configure your MCP client (like Claude Desktop) to use this server:

{
  "mcpServers": {
    "threads": {
      "command": "threads-mcp",
      "env": {
        "THREADS_ACCESS_TOKEN": "your-access-token",
        "THREADS_USER_ID": "your-user-id"
      }
    }
  }
}

Example Tool Calls

Get Your Profile

{
  "name": "threads_get_profile",
  "arguments": {}
}

Create a Thread

{
  "name": "threads_create_thread",
  "arguments": {
    "text": "Hello from the Threads MCP Server! 🚀",
    "replyControl": "everyone"
  }
}

Get Thread Insights

{
  "name": "threads_get_insights",
  "arguments": {
    "threadId": "thread-id-here",
    "metrics": ["views", "likes", "replies", "reposts"]
  }
}

Reply to a Thread

{
  "name": "threads_reply_to_thread",
  "arguments": {
    "threadId": "thread-id-to-reply-to",
    "text": "Great post!",
    "replyControl": "accounts_you_follow"
  }
}

Development

Project Structure

threads-mcp/
├── src/
│   ├── client/           # Threads API client
│   │   ├── __tests__/    # Client tests
│   │   └── threads-client.ts
│   ├── server/           # MCP server implementation
│   │   ├── __tests__/    # Server tests
│   │   └── server.ts
│   ├── types/            # TypeScript types & Zod schemas
│   │   ├── __tests__/    # Type tests
│   │   └── threads.ts
│   └── index.ts          # Entry point
├── dist/                 # Compiled output
├── coverage/             # Test coverage reports
└── tests/                # Integration tests

Available Scripts

# Development
pnpm run dev              # Run in development mode with tsx
pnpm run build            # Compile TypeScript to JavaScript

# Testing
pnpm test                 # Run tests once
pnpm test:watch          # Run tests in watch mode
pnpm test:coverage       # Generate coverage report

# Code Quality
pnpm run lint            # Lint code with ESLint
pnpm run format          # Format code with Prettier

Running Tests

The project has comprehensive test coverage (>90%):

# Run all tests
pnpm test

# Run with coverage
pnpm test:coverage

# Watch mode for development
pnpm test:watch

Code Quality

# Lint your code
pnpm run lint

# Format code
pnpm run format

API Reference

ThreadsClient

The core client for interacting with the Threads API.

Constructor

const client = new ThreadsClient({
  accessToken: string;
  userId: string;
  apiVersion?: string; // Optional, defaults to 'v1.0'
});

Methods

• getProfile(fields?: string[]): Promise<ThreadsUser>
• getThreads(params?: GetMediaParams): Promise<ThreadsMedia[]>
• getThread(threadId: string, fields?: string[]): Promise<ThreadsMedia>
• createThread(params: CreateThreadParams): Promise<CreateThreadResponse>
• getThreadInsights(threadId: string, params: GetInsightsParams): Promise<ThreadsInsights[]>
• getUserInsights(params: GetInsightsParams): Promise<ThreadsInsights[]>
• getReplies(threadId: string, params?: GetRepliesParams): Promise<ThreadsReplies>
• getConversation(threadId: string, params?: GetRepliesParams): Promise<ThreadsConversation>
• replyToThread(threadId: string, text: string, replyControl?: string): Promise<CreateThreadResponse>
• validateToken(): Promise<boolean>

Error Handling

The client includes comprehensive error handling:

import { ThreadsAPIError } from 'threads-mcp';

try {
  await client.createThread({ text: 'Hello!' });
} catch (error) {
  if (error instanceof ThreadsAPIError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  }
}

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Write tests for new features (maintain >90% coverage)
• Follow the existing code style
• Update documentation as needed
• Use conventional commits (enforced by Git hooks)

Git Hooks

This project uses Husky to enforce code quality:

• pre-commit: Runs linting, formatting, and type checking
• pre-push: Runs full test suite, coverage check, and build verification
• commit-msg: Validates commit message format (conventional commits)

See docs/GIT_HOOKS.md for detailed information about Git hooks.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Copyright (c) 2025 Pegasus Heavy Industries LLC

Support

• 📚 Threads API Documentation
• 🐛 Report Issues
• 💬 MCP Protocol Documentation

Acknowledgments

• Built with MCP SDK
• Powered by Threads API
• Type validation with Zod
• Testing with Vitest

---

Made with ❤️ by Pegasus Heavy Industries LLC