🚀 Enterprise Threads MCP Server

A comprehensive MCP (Model Context Protocol) server for professional Threads management with enterprise-grade analytics, AI-powered optimization, and automation features.

🎯 Enterprise-Ready Platform

Complete social media management solution with advanced analytics, content optimization, and professional automation tools for businesses and power users.

✨ Enterprise Features

📊 Phase 3A: Enhanced Analytics & Performance Analysis

• Advanced Insights: Demographic breakdowns, geographic analysis, time-series data
• Audience Analytics: Detailed follower demographics and behavior patterns
• Engagement Trends: Comprehensive trend analysis with growth projections
• AI-Driven Optimization: Optimal posting times and performance recommendations
• Business Intelligence: Professional reporting with comprehensive metrics

🚀 Phase 3B: Professional Content Creation & Automation

• AI Hashtag Suggestions: Smart, industry-specific hashtag recommendations
• Content Optimization: Professional analysis with scoring and recommendations
• Advanced Scheduling: Automation with optimal timing and recurring posts
• Bulk Operations: Performance analysis, content audit, and data export
• Website Integration: Embed feeds, share buttons, and cross-platform sync
• Carousel Posts: Multi-media posts with accessibility features

🎯 Core Management Features

• Content Management: Create, view, search, and delete your threads
• Analytics Dashboard: Real-time insights and performance metrics
• Interaction Management: Handle replies, mentions, and user relationships
• Search & Discovery: Advanced search with filters and content discovery
• Publishing Control: Rate limits, scheduling, and automation

🚀 Quick Start

Installation

npm install -g threads-mcp-server

⚠️ IMPORTANT: Business Account Required

This MCP server requires a verified Instagram Business Account with proper API access.

Prerequisites Setup

1. Instagram Business Account:

• Convert your Instagram to a Business Account
• Complete Meta Business verification (1-3 days)
• Ensure you have 100+ followers for demographic analytics

2. Meta Developer Setup:

• Create a Meta Developer App at developers.facebook.com
• Add "Threads API" product to your app
• Request these required scopes:
  • threads_basic
  • threads_content_publish
  • threads_manage_insights
  • threads_read_replies

3. OAuth Access Token:

• Complete OAuth flow with your business Instagram account
• Generate an access token with all required scopes

Configuration

Create a .env file with your Threads access token:

THREADS_ACCESS_TOKEN=your_access_token_here

✅ Validate Your Setup

After configuration, test your setup:

# Run the MCP server and test
@threads validate_setup

This will check:

• ✅ Token validity
• ✅ Required scopes
• ✅ Business account access
• ✅ API permissions

Follow any recommendations provided by the validation tool.

Claude Desktop Setup

Add to your Claude Desktop configuration:

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

🛠️ Available Tools

Profile & Account Management

get_my_profile

Get your Threads profile information

{
  fields?: string[] // Profile fields to retrieve
}

get_my_insights

Get analytics for your account

{
  metrics: string[];    // e.g., ['followers_count', 'posts_count']
  period?: string;      // 'day', 'week', 'days_28', 'month', 'lifetime'
  since?: string;       // ISO 8601 date
  until?: string;       // ISO 8601 date
}

get_publishing_limit

Check your current posting quotas and limits

{} // No parameters needed

Content Management

get_my_threads

Get your own threads/posts

{
  fields?: string[];    // Thread fields to retrieve
  limit?: number;       // Number of threads to get
  since?: string;       // ISO 8601 date filter
  until?: string;       // ISO 8601 date filter
}

publish_thread

Create and publish a new thread using Threads API two-step process

{
  text: string;           // Thread content (required)
  media_type?: string;    // 'TEXT', 'IMAGE', 'VIDEO'
  media_url?: string;     // URL for media content
  location_name?: string; // Location tagging
}

Note: This function implements the proper two-step Threads publishing flow: first creates a media container, then publishes it. The response includes both the container ID and final thread ID.

delete_thread

Delete one of your threads

{
  thread_id: string; // ID of your thread to delete
}

search_my_threads

Search within your own threads

{
  query: string;   // Search keywords
  limit?: number;  // Threads to search through
}

Thread Interactions

get_thread_replies

Get replies to your specific thread

{
  thread_id: string;    // Your thread ID
  fields?: string[];    // Reply fields to retrieve
}

manage_reply

Hide or show replies to your threads

{
  reply_id: string; // Reply ID to manage
  hide: boolean;    // true to hide, false to show
}

get_mentions

Get threads where you are mentioned

{
  fields?: string[];  // Fields to retrieve
  limit?: number;     // Number of mentions
}

create_reply

Reply to a specific thread or post

{
  reply_to_id: string;     // Thread/post ID to reply to (required)
  text: string;            // Reply content (required)
  media_type?: string;     // 'TEXT', 'IMAGE', 'VIDEO'
  media_url?: string;      // Media URL for IMAGE/VIDEO
  reply_control?: string;  // 'everyone', 'accounts_you_follow', etc.
}

Note: Uses two-step process like publish_thread. Creates real replies that appear in thread conversations.

create_thread_chain

Create connected reply chains for threaded conversations

{
  parent_thread_id: string;  // Starting thread ID (required)
  replies: Array<{           // Array of replies (required)
    text: string;            // Reply text
    reply_control?: string;  // Who can reply to this reply
  }>;
}

Note: Creates true threaded conversations where each reply responds to the previous one, enabling Twitter-like thread chains.

Analytics & Performance

get_thread_insights

Get performance metrics for your specific thread

{
  thread_id: string;    // Your thread ID
  metrics: string[];    // e.g., ['views', 'likes', 'replies']
  period?: string;      // Time period for metrics
}

🔧 Setup Validation & Diagnostics

validate_setup

NEW in v5.0.0 - Comprehensive setup validation and diagnostics

{
  check_scopes?: boolean;          // Check if all required scopes are present
  required_scopes?: string[];      // Custom list of required scopes to check
}

What it checks:

• ✅ Access token validity
• ✅ Required API scopes
• ✅ Business account verification
• ✅ Profile access permissions
• 📋 Provides specific setup recommendations

Example response:

{
  "status": "valid",
  "token_validation": { "valid": true },
  "scope_validation": { "hasRequired": true, "missing": [] },
  "profile_access": { "success": true },
  "setup_recommendations": ["✅ Setup appears to be correct!"]
}

🏢 Enterprise Analytics & Automation Tools (Phase 3)

📊 Advanced Analytics

get_enhanced_insights

Get comprehensive analytics with demographic breakdowns

{
  thread_id?: string;           // Optional thread ID for media insights
  metrics: string[];            // views, likes, replies, followers_count, follower_demographics
  period?: string;              // day, week, month, lifetime
  breakdown?: string[];         // country, city, age, gender
  since?: string;               // ISO 8601 start date
  until?: string;               // ISO 8601 end date
}

get_audience_demographics

Detailed audience demographic analysis

{
  categories: string[];         // country, age, gender, city
  period?: string;             // day, week, month, lifetime
  breakdown?: string;          // Demographic breakdown level
}

get_engagement_trends

Time-series analysis of engagement patterns

{
  metrics: string[];           // views, likes, replies, shares
  timeframe?: string;          // week, month, quarter
  granularity?: string;        // daily, weekly
}

get_follower_growth_analytics

Follower growth analysis with projections

{
  period?: string;             // month, quarter, year
  include_projections?: boolean; // Include growth forecasts
  projection_days?: number;    // Days to project forward
}

analyze_best_posting_times

AI-driven optimal posting time analysis

{
  analysis_period?: string;    // week, month, quarter
  timezone?: string;           // User's timezone
  content_type?: string;       // general, promotional, educational
}

get_content_performance_report

Comprehensive performance reporting

{
  report_type: string;         // summary, detailed, top_performers
  period: string;              // week, month, quarter
  metrics: string[];           // Performance metrics to include
  include_comparisons?: boolean; // Period-over-period comparisons
}

🚀 Professional Content Creation & Automation

auto_hashtag_suggestions

AI-powered hashtag recommendations

{
  content: string;             // Content to analyze
  media_url?: string;          // Optional media for visual analysis
  suggestion_settings?: {
    count?: number;            // Number of suggestions (1-10)
    style?: string;            // trending, niche, branded, mixed
    exclude_overused?: boolean; // Filter out overused hashtags
    industry_focus?: string;   // Industry/niche focus
  }
}

content_optimization_analysis

Professional content analysis with recommendations

{
  content: string;             // Content to analyze
  analysis_type?: string;      // engagement, reach, accessibility, seo, comprehensive
  target_audience?: {
    demographics?: string[];   // Target demographic groups
    interests?: string[];      // Target interests
    timezone?: string;         // Primary audience timezone
  };
  optimization_goals?: string[]; // increase_engagement, expand_reach, etc.
}

schedule_post

Advanced scheduling with automation features

{
  text: string;                // Post content
  media_url?: string;          // Optional media URL
  schedule_time?: string;      // ISO 8601 datetime for scheduling
  automation_settings?: {
    auto_optimize_time?: boolean; // Auto-optimize posting time
    recurring?: string;        // none, daily, weekly, monthly
    auto_hashtags?: boolean;   // Auto-add relevant hashtags
    content_variation?: boolean; // Create variations for recurring posts
  };
  timezone?: string;           // Timezone for scheduling
}

create_carousel_post

Multi-media carousel posts with accessibility

{
  media_urls: string[];        // 2-10 image/video URLs
  text: string;                // Post caption
  alt_texts?: string[];        // Alt text for accessibility
  carousel_settings?: {
    auto_alt_text?: boolean;   // Generate alt text automatically
    aspect_ratio?: string;     // square, portrait, landscape
    thumbnail_selection?: string; // auto, first, custom
  }
}

bulk_post_management

Bulk operations and content management

{
  action: string;              // analyze_performance, content_audit, export_data
  filters?: {
    date_range?: { start: string; end: string };
    content_type?: string;     // text, image, video, carousel
    performance_threshold?: string; // low, medium, high
  };
  bulk_operations?: {
    add_hashtags?: string[];   // Hashtags to add
    update_alt_text?: boolean; // Update alt text
    archive_low_performers?: boolean; // Archive underperforming posts
  }
}

website_integration_setup

Website integration and cross-platform sync

{
  integration_type: string;    // embed_feed, share_buttons, webhook_setup, auto_crosspost
  website_config?: {
    domain?: string;           // Website domain
    platform?: string;        // wordpress, shopify, custom, react, vue, angular
    styling_preferences?: {
      theme?: string;          // light, dark, auto
      layout?: string;         // grid, list, carousel
      post_count?: number;     // Number of posts to display
    }
  };
  automation_settings?: {
    auto_sync?: boolean;       // Auto-sync new posts
    crosspost_enabled?: boolean; // Enable cross-posting
    webhook_url?: string;      // Webhook endpoint URL
  }
}

📊 Test Results

Latest Test Results: ✅ 10+ functions working + Complete Phase 1 implementation!

Core Functions

| Tool | Status | Notes | |------|--------|-------| | get_my_profile | ✅ Working | Full profile data | | get_my_threads | ✅ Working | Returns thread list | | search_my_threads | ✅ Working | Client-side filtering | | get_publishing_limit | ✅ Working | Quota information | | publish_thread | ✅ Working | Successfully publishes! | | delete_thread | ⚠️ Limited | Error 400 (endpoint issue) | | get_my_insights | ⚠️ Limited | Error 500 (permission/endpoint) |

Phase 1: Complete Engagement & Advanced Posting (NEW)

| Tool | Status | Notes | |------|--------|-------| | create_reply | ✅ Phase 1 | Creates real replies! | | create_thread_chain | ✅ Phase 1 | True threaded conversations! | | quote_post | ✅ Phase 1A | Quote tweets with commentary! | | like_post | 🔧 Phase 1A | Implemented with fallback patterns | | unlike_post | 🔧 Phase 1A | Implemented with fallback patterns | | repost_thread | 🔧 Phase 1A | Implemented with fallback patterns | | unrepost_thread | 🔧 Phase 1A | Implemented with fallback patterns | | get_post_likes | 🔧 Phase 1A | Implemented with fallback patterns | | create_post_with_restrictions | ✅ Phase 1B | Advanced posts with hashtags! | | schedule_post | ✅ Phase 1B | Future post scheduling! |

Total Tools: 21 functions (11 original + 10 new Phase 1 features)

💡 Usage Examples

Content Creation & Management

# Publish a new thread
@threads publish "Just testing my personal Threads manager! 🚀"

# Get my recent threads
@threads get my recent threads limit 10

# Search my content
@threads search "project" in my threads

Phase 1A: Engagement & Interaction

# Quote another post with your commentary
@threads quote post 123456 "This is exactly what I was thinking! Adding my perspective..."

# Like and unlike posts
@threads like post 123456
@threads unlike post 123456

# Repost content (share to your timeline)
@threads repost thread 123456
@threads unrepost thread 123456

# Get engagement data
@threads get likes for post 123456 limit 50

Phase 1B: Advanced Posting

# Create post with hashtags and restrictions
@threads create advanced post "My latest project update!" 
  hashtags: ["WebDev", "MCP", "Threads"]
  mentions: ["techfriend", "developer"]
  reply_control: "followers_only"
  location: "San Francisco"

# Schedule posts for future publishing
@threads schedule post "Good morning! ☀️" 
  for: "2025-08-25T08:00:00+07:00"
  reply_control: "everyone"

Reply & Thread Management

# Reply to a specific thread
@threads reply to thread 123456 "Great post! Thanks for sharing"

# Create a thread chain (multiple connected replies)
@threads create chain from thread 123456 with replies:
- "First point in my response 🧵"  
- "Second point continuing the thought"
- "Final point wrapping up"

# Get replies to my thread
@threads get replies to my thread 123456

Analytics & Performance

# Check my publishing limits
@threads check my publishing quotas

# Get my profile stats
@threads get my profile information

# Get thread performance (if available)
@threads get insights for thread 123456

Interaction Management

# Get replies to my thread
@threads get replies for my thread 123456

# Hide a reply
@threads hide reply 789012

# Get my mentions
@threads get where I am mentioned

🔧 Technical Details

Personal Focus Benefits

• No External User Limitations: Only works with your own content
• Full Access: All permissions work on your own data
• Reliable: No privacy restrictions or access denials
• Fast: Direct API calls without workarounds

Error Handling

• Automatic retry for transient errors
• Clear error messages for permission issues
• Graceful handling of API limitations

Rate Limiting

• Built-in exponential backoff
• Respects Threads API rate limits
• Smart retry logic for temporary failures

🚨 Important Notes

Permissions Required

Ensure your Threads app has these permissions enabled:

• threads_basic - Basic thread access
• threads_content_publish - Create/publish content
• threads_delete - Delete threads (if using delete functionality)
• threads_manage_insights - Analytics access
• threads_manage_replies - Reply management

Limitations

• Delete Function: Currently returns 400 error (API endpoint needs verification)
• Insights: Some analytics endpoints return 500 error (may need additional permissions)
• Personal Only: Designed only for your own content management

📈 Roadmap

Planned Improvements

• [ ] Fix delete thread endpoint
• [ ] Resolve insights API issues
• [ ] Add batch operations
• [ ] Enhanced search filters
• [ ] Thread scheduling
• [ ] Content analytics dashboard

🤝 Contributing

This is a focused personal management tool. Feature requests should align with personal Threads management use cases.

📄 License

MIT

🎯 Perfect For:

• Content Creators: Manage your Threads content efficiently
• Social Media Managers: Handle personal brand accounts
• Analysts: Track your own content performance
• Developers: Integrate Threads into personal workflows

Focus: Your content, your control, your insights! 🚀