# Threads MCP Server

`threads-mcp` is a stdio MCP server for the official Threads API. It is designed to stay close to the published Meta Threads documentation while exposing a practical MCP tool surface for auth, publishing, reading, moderation, insights, discovery, locations, and setup diagnostics.

The current build is intentionally limited to officially documented Threads capabilities and the official Postman collection. It does not rely on undocumented fallback endpoints or convenience wrappers that would be difficult to maintain in a public package.

## Highlights

- Official Threads API scope only
- MCP tools for auth, profile lookup, publishing, reading, replies, insights, search, locations, oEmbed, and diagnostics
- Publish inputs modeled in camelCase and serialized internally to the snake_case parameters expected by Threads
- Multi-step carousel publishing support
- Shared client layer for retries, polling, pagination, and normalized Meta API errors

## Quick start

1. Install dependencies:

```bash
npm install
```

2. Build the server:

```bash
npm run build
```

3. Create your local environment file and set at least `THREADS_ACCESS_TOKEN`.

4. If you still need a token, run the local OAuth helper:

```bash
npm run auth:token
```

5. Start the server:

```bash
node dist/index.js
```

6. Call `validate_setup` before using publish or moderation flows against a real account.

## Tool catalog

### Auth

- `exchange_code_for_token`
- `get_long_lived_access_token`
- `refresh_access_token`
- `get_app_access_token`

### Profiles and discovery

- `get_me`
- `get_profile`
- `get_profile_threads`

### Publishing and lifecycle

- `get_publishing_limit`
- `create_thread_container`
- `publish_thread`
- `create_and_publish_thread`
- `repost_thread`
- `delete_thread`

### Reading and replies

- `get_threads`
- `get_thread`
- `get_replies`
- `get_thread_conversation`
- `get_pending_replies`
- `manage_reply`
- `manage_pending_reply`

### Insights, search, and embeds

- `get_user_insights`
- `get_thread_insights`
- `search_threads`
- `get_mentions`
- `get_oembed`

### Locations and diagnostics

- `search_locations`
- `get_location`
- `validate_setup`

## Explicitly out of scope for v1

- Webhooks
- Embedded OAuth callback hosting
- Any undocumented fallback endpoints or convenience features that are not covered by the official docs or official Postman collection

## Architecture

The server is split into a few clear layers:

- `src/index.ts` bootstraps the MCP stdio transport.
- `src/threads/client.ts` owns authenticated HTTP calls, retries, pagination, polling, and normalized Meta API errors.
- `src/tools/` contains one module per tool family plus shared schemas.

The publish input model is exposed as a single public discriminated union covering `text`, `image`, `video`, `carousel`, and `reply`.

## Prerequisites

You need all of the following before the server can make live API calls:

- A Meta app configured for the Threads use case
- A Threads user access token for the account you want to operate on
- Advanced access and app review where your integration requires it
- Node.js 20+ on the machine where the server will run

## Environment variables

Required for most user-token tools:

- `THREADS_ACCESS_TOKEN`

Optional:

- `THREADS_APP_ID`
- `THREADS_APP_SECRET`
- `THREADS_REDIRECT_URI`
- `THREADS_API_BASE_URL`
- `THREADS_USER_ID`
- `THREADS_MAX_RETRIES`
- `THREADS_RETRY_BASE_DELAY_MS`
- `THREADS_TIMEOUT_MS`
- `THREADS_PUBLISH_STATUS_TIMEOUT_MS`
- `THREADS_PUBLISH_STATUS_POLL_INTERVAL_MS`

Copy `.env.example` and set at least the access token. `THREADS_APP_ID` and `THREADS_APP_SECRET` are also needed for the auth helper tools and for `get_oembed` when you do not pass an explicit app access token.

### Where to get `THREADS_APP_ID`

- Open your app in the Meta for Developers dashboard: https://developers.facebook.com/apps/
- Open the app created with the **Threads** use case
- Go to `Use Cases` -> `Threads` -> `Customize` -> `Settings`
- Copy the **Threads App ID** from that page
- Use that value as `THREADS_APP_ID`

Important:

- Do not use the general Meta app ID from the top-level app dashboard or settings page
- Use the Threads use-case-specific credentials from `Use Cases` -> `Threads` -> `Customize` -> `Settings`

`THREADS_APP_SECRET` comes from the same Threads use-case settings page. Keep it private.

## Token helper script

The repository includes a local OAuth helper that follows the Meta Threads access-token flow:

1. Open the Threads authorization window
2. Receive the authorization code on a local callback URL
3. Exchange it for a short-lived token
4. Exchange that for a long-lived token
5. Save the result into `.env` as `THREADS_ACCESS_TOKEN`

Setup:

- Add your Meta app credentials to `.env`
- Make sure your app's valid OAuth redirect URI matches `THREADS_REDIRECT_URI`

Run:

```bash
npm run auth:token
```

Optional flags:

- `--redirect-uri http://127.0.0.1:8788/callback`
- `--env-file .env.local`
- `--no-open`

## Required scopes by tool family

- `threads_basic`
  Used by `get_me`, `get_profile`, `get_threads`, `get_thread`, and baseline setup validation.
- `threads_content_publish`
  Used by `get_publishing_limit`, `create_thread_container`, `publish_thread`, and `create_and_publish_thread`.
- `threads_read_replies`
  Used by `get_replies` and safe reply-read probes in `validate_setup`.
- `threads_manage_replies`
  Used by `manage_reply`.
- `threads_manage_insights`
  Used by `get_user_insights` and `get_thread_insights`.
- `threads_keyword_search`
  Used by `search_threads`.
- `threads_profile_discovery`
  Used by `get_profile` and `get_profile_threads` for public account discovery scenarios.
- `threads_location_tagging`
  Used by `search_locations`, `get_location`, and publish flows that set `locationId`.
- `threads_delete`
  Used by `delete_thread`.

`validate_setup` performs safe probes to infer access for `threads_basic`, `threads_content_publish`, `threads_read_replies`, `threads_manage_insights`, `threads_keyword_search`, `threads_profile_discovery`, and `threads_location_tagging`. It deliberately does not perform destructive probes for `threads_manage_replies` or `threads_delete`, so those scopes are not actively validated by setup.

## Publish behavior

The server models official container options in camelCase and serializes them internally to the snake_case parameters expected by the Threads API.

Supported inputs include:

- Common fields: `text`, `replyControl`, `replyToId`, `quotePostId`, `topicTag`, `locationId`, `textEntities`, `allowlistedCountryCodes`
- Text-only fields: `linkAttachment`, `pollAttachment`, `textAttachment`, `gifAttachment`, `enableReplyApprovals`, `autoPublishText`, `isGhostPost`
- Image or video fields: `imageUrl`, `videoUrl`, `altText`, `isSpoilerMedia`
- Carousel items: validated arrays of image or video items with per-item media fields

Carousel publishing follows the official multi-step flow:

1. Create one item container per image or video with `is_carousel_item=true`
2. Create the parent carousel container with `children=[...]`
3. Publish the parent container

## Coverage notes

The repository currently covers these official Threads API families:

- Authorization helpers
- Publishing, including quote posts, repost publishing, and container status polling
- User profile lookup and public profile post retrieval
- Threads media retrieval
- Reply retrieval, flattened conversations, pending replies, hide and unhide, and approve and ignore flows
- User and post insights
- Keyword search and mentions
- Location search and location retrieval
- oEmbed
- Setup diagnostics

## Local MCP config example

Example Claude Desktop style config:

```json
{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/absolute/path/to/threads-mcp/dist/index.js"],
      "env": {
        "THREADS_ACCESS_TOKEN": "thdt_your_user_access_token",
        "THREADS_APP_ID": "optional_app_id",
        "THREADS_APP_SECRET": "optional_app_secret"
      }
    }
  }
}
```

If you later publish this package as a CLI, the `command` can become `threads-mcp`.

## Publishing

The package metadata is already configured for npm publication as a public package:

- package name: `threads-mcp`
- current version: `0.0.0`
- CLI entrypoint: `threads-mcp`
- publish access: `public`

Before publishing, run:

```bash
npm run build
npm test
npm publish --access public
```

`prepublishOnly` is configured to run the build and test steps automatically during `npm publish`.

## Development

Install dependencies once Node.js is available:

```bash
npm install
npm run build
npm test
```

Suggested manual checks:

1. Run `npm run build` to verify TypeScript compilation.
2. Run `npm test` to execute the schema, client, and tool registration tests.
3. Start the server with `node dist/index.js`.
4. Call `validate_setup` first with a real token.
5. Exercise `create_thread_container` and `publish_thread` against a test Threads account.

## Known limitations

- Transport is stdio only in v1
- There is no embedded OAuth callback server; token exchange helpers are exposed as MCP tools instead
- `validate_setup` cannot safely verify `threads_manage_replies` without performing a state-changing moderation call
- `validate_setup` also does not perform a state-changing delete probe
- `create_and_publish_thread` intentionally rejects `autoPublishText=true` because that flag conflicts with the tool's explicit two-step contract
- Reply publishing is modeled as a dedicated `reply` variant backed by the official `reply_to_id` parameter and currently targets text replies in the public schema
- Verification of live API behavior still depends on valid app credentials, approved scopes, and a real Threads account

## Sources used for API scope and endpoint selection

- Meta Threads API reference: https://developers.facebook.com/docs/threads/reference
- Meta Threads publishing reference: https://developers.facebook.com/docs/threads/reference/publishing
- Meta official Postman workspace: https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api