Skip to main content
Glama
Threads API MCP Server

Threads API MCP Server

by VladMontana

Threads API MCP Server

A lightweight, production-ready FastMCP server in Python that interfaces with the Meta Threads Graph API (https://graph.threads.net/v1.0).

This server exposes specialized MCP tools for AI agents (such as Hermes Agent, Claude Desktop, Cursor, or Antigravity) to fetch profile details, inspect recent posts, retrieve post engagement analytics (views, likes, replies, reposts, quotes), and traverse conversation reply trees.


Features & MCP Tools

Tool Name

Parameters

Description

get_profile_info

None

Retrieves authenticated user ID, username, bio, avatar URL, and web profile URL.

list_recent_posts

limit (default: 25), after, before

Fetches recent user posts with full text, media type, timestamps, permalinks, and pagination cursor.

get_post_details

media_id (str)

Retrieves detailed metadata for a single Threads post.

get_post_analytics

media_id (str)

Returns breakdown of views, likes, replies, reposts, and quotes for a given post.

get_account_analytics

metric_types (list), days_back (default: 7)

Fetches aggregated account-level metrics over a timeframe.

fetch_post_replies

media_id (str), reverse_sort (bool), limit, after

Retrieves top-level and nested replies for a post.

export_posts

limit (default: 50)

Exports posts as a flat, clean JSON list ready for archiving or vector embedding indexing.


Related MCP server: Enterprise Threads MCP Server

Tech Stack & Architecture

  • Python 3.11+ managed with uv

  • MCP SDK: mcp (FastMCP interface)

  • HTTP Client: httpx (async client with exponential backoff & rate limit handling)

  • Validation & Schemas: pydantic v2

  • Configuration: pydantic-settings / .env


Quickstart & Setup

1. Prerequisites

Ensure you have Python 3.11+ and uv installed:

# Verify uv installation
uv --version

2. Environment Configuration

Copy the sample .env.example file and provide your Meta Threads Graph API credentials:

cp .env.example .env

Edit .env:

# Meta Threads User Access Token (Required)
THREADS_ACCESS_TOKEN=your_long_lived_threads_token_here

# User ID (Optional, default: "me")
THREADS_USER_ID=me

# API Base URL (Optional)
THREADS_API_BASE_URL=https://graph.threads.net/v1.0
TIP

To obtain a long-lived Threads Access Token, create an application in theMeta for Developers Portal, add the Threads API use case, and grant the following permissions:

  • threads_basic

  • threads_content_publish

  • threads_read_replies

  • threads_manage_replies

  • threads_manage_insights


Running the Server

Stdio Transport (Standard MCP)

uv run python -m threads_mcp.server

Or using the CLI entrypoint:

uv run threads-mcp

Agent Configurations

1. Hermes Agent (~/.hermes/config.yaml)

mcp_servers:
  threads:
    command: "uv"
    args:
      - "--directory"
      - "/absolute/path/to/threads-mcp"
      - "run"
      - "python"
      - "-m"
      - "threads_mcp.server"
    env:
      THREADS_ACCESS_TOKEN: "your_long_lived_threads_token_here"

2. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "threads": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Users\\Влад\\Desktop\\treads-mcp",
        "run",
        "python",
        "-m",
        "threads_mcp.server"
      ],
      "env": {
        "THREADS_ACCESS_TOKEN": "your_long_lived_threads_token_here"
      }
    }
  }
}

Running Tests

Run the test suite with uv run pytest:

uv run pytest tests/ -v

Error Handling

  • OAuth & Auth Expiration (401 / code 190): Caught and returned as readable instructions to refresh tokens.

  • Rate Limiting (429 / codes 4, 17, 32, 613): Automatic exponential backoff retries.

  • Unsupported Insights: Gracefully handles media types that do not support specific insight metrics without crashing.

Available Tools

7 tools
export_postsA

Export recent posts formatted as a clean flat JSON list for archiving, analysis, or vector embeddings.

Args: limit: Number of posts to export (default 50, max 100).

Returns: JSON string containing flat simplified post items with ID, text, timestamp, and URL.

Inputs: limit. Returns: result

fetch_post_repliesA

Fetch replies and comments attached to a specific Threads post.

Args: media_id: Unique Threads post/media ID. reverse_sort: If True, returns newest replies first. If False, returns chronological order. limit: Max replies to fetch (default 50). after: Pagination cursor for next page of replies.

Returns: JSON string containing list of replies (id, text, timestamp, username, permalink) and cursors.

Inputs: media_id (required), after, limit, reverse_sort. Returns: result

get_account_analyticsA

Fetch aggregated engagement metrics for the account over a specified time window.

Args: metric_types: List of metrics (e.g. ["views", "likes", "reposts", "quotes", "followers_count"]). days_back: Number of past days to query (default: 7).

Returns: JSON string containing aggregated metric totals.

Inputs: days_back, metric_types. Returns: result

get_post_analyticsA

Fetch engagement analytics (views, likes, replies, reposts, quotes) for a specific post.

Args: media_id: Unique Threads post/media ID.

Returns: JSON string containing numeric metrics (views, likes, replies, reposts, quotes) and raw data.

Inputs: media_id (required). Returns: result

get_post_detailsA

Fetch detailed metadata for a single Threads post.

Args: media_id: Unique Threads post/media ID.

Returns: JSON string with post content, author username, timestamp, permalink, and media info.

Inputs: media_id (required). Returns: result

get_profile_infoA

Fetch the authenticated Threads user's profile information.

Returns: JSON string containing user id, username, bio, avatar URL, and profile link.

Inputs: no named parameters. Returns: result

list_recent_postsA

Fetch recent posts from the authenticated user's Threads account.

Args: limit: Number of posts to retrieve (1 to 100, default 25). after: Pagination cursor for fetching subsequent posts page. before: Pagination cursor for fetching previous posts page.

Returns: JSON string with list of posts (id, text, media_type, timestamp, permalink) and pagination cursors.

Inputs: after, limit, before. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 7 tools

    Disambiguation4/5

    Most tools map to a distinct resource and action, such as profile, post list, post details, post analytics, account analytics, replies, and export. The only real overlap risk is between list_recent_posts and export_posts, but their output purpose and shape are different enough to avoid serious misselection.

    Naming Consistency4/5

    Tool names generally follow a clear verb_noun pattern, e.g. get_profile_info, list_recent_posts, get_post_details. The main inconsistency is using get, list, fetch, and export as interchangeable retrieval verbs, but no convention mixing like camelCase or inconsistent singular/plural occurs.

    Tool Count5/5

    Seven tools is well-scoped for a Threads read-and-analytics server. Each tool covers a coherent slice of functionality without unnecessary bloat or padding.

    Completeness4/5

    The tool set covers profile retrieval, recent posts, post details, replies, per-post analytics, account analytics, and data export, so common read-only workflows are complete. Write/publish and search operations are absent, but they appear outside this server's apparent scope.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI assistants to manage Instagram and Threads accounts — publish content, handle comments, view insights, search hashtags, and manage DMs through the Meta Graph API.
      59
      38 npm
      14
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI agents to manage a Threads profile through Meta's API, including posting, threads, replies, reply moderation, and insights.
      30
      21 npm
      4
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to interact with Threads via MCP, including sub-80ms keyword search, full nested discussion tree extraction, replying to any external thread, publishing posts, fetching user profiles and threads, trending topics, and engagement actions like likes and reposts.
      3
      -