# 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. |

---

## 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:

```bash
# Verify uv installation
uv --version
```

### 2. Environment Configuration

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

```bash
cp .env.example .env
```

Edit `.env`:
```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 the [Meta for Developers Portal](https://developers.facebook.com/), 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)

```bash
uv run python -m threads_mcp.server
```

Or using the CLI entrypoint:

```bash
uv run threads-mcp
```

---

## Agent Configurations

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

```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`)

```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`:

```bash
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.