Threads API MCP Server
Provides tools for interacting with a user's Threads account via the Meta Threads Graph API, including fetching profile info, recent posts, post details, engagement analytics, and replies.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Threads API MCP Server show me my recent Threads posts with their engagement metrics"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| None | Retrieves authenticated user ID, username, bio, avatar URL, and web profile URL. |
|
| Fetches recent user posts with full text, media type, timestamps, permalinks, and pagination cursor. |
|
| Retrieves detailed metadata for a single Threads post. |
|
| Returns breakdown of views, likes, replies, reposts, and quotes for a given post. |
|
| Fetches aggregated account-level metrics over a timeframe. |
|
| Retrieves top-level and nested replies for a post. |
|
| 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
uvMCP SDK:
mcp(FastMCP interface)HTTP Client:
httpx(async client with exponential backoff & rate limit handling)Validation & Schemas:
pydanticv2Configuration:
pydantic-settings/.env
Quickstart & Setup
1. Prerequisites
Ensure you have Python 3.11+ and uv installed:
# Verify uv installation
uv --version2. Environment Configuration
Copy the sample .env.example file and provide your Meta Threads Graph API credentials:
cp .env.example .envEdit .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.0To 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_basicthreads_content_publishthreads_read_repliesthreads_manage_repliesthreads_manage_insights
Running the Server
Stdio Transport (Standard MCP)
uv run python -m threads_mcp.serverOr using the CLI entrypoint:
uv run threads-mcpAgent 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/ -vError 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 toolsexport_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
Scored across 7 tools
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.
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.
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.
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
Publish, reply, moderate, search and read insights on your Threads (threads.com) account.
Threads scheduler for AI agents: write, schedule and publish posts, review replies, read insights.
Threads public posts, replies and profiles, with view counts, keyword and account search.
Export any public Threads profile's posts, followers & following into Claude, no login or API key
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI assistants to manage Instagram and Threads accounts — publish content, handle comments, view insights, search hashtags, and manage DMs through the Meta Graph API.5938 npm14MIT
- AlicenseCqualityDmaintenanceEnables professional Threads management with advanced analytics, AI-powered content optimization, and automation features.45MIT
- AlicenseAqualityBmaintenanceEnables AI agents to manage a Threads profile through Meta's API, including posting, threads, replies, reply moderation, and insights.3021 npm4MIT
- FlicenseNot gradedqualityBmaintenanceEnables 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-