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

Related MCP server: meta-mcp

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

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.