Threads MCP Server

threads-mcp — это сервер MCP через stdio для официального API Threads. Он разработан так, чтобы максимально соответствовать опубликованной документации Meta Threads, предоставляя при этом практичный набор инструментов MCP для аутентификации, публикации, чтения, модерации, аналитики, поиска, работы с локациями и диагностики настройки.

Текущая сборка намеренно ограничена официально задокументированными возможностями Threads и официальной коллекцией Postman. Она не полагается на недокументированные резервные конечные точки или вспомогательные обертки, которые было бы сложно поддерживать в публичном пакете.

Основные возможности

• Только официальные области применения API Threads

• Инструменты MCP для аутентификации, поиска профилей, публикации, чтения, ответов, аналитики, поиска, локаций, oEmbed и диагностики

• Входные данные для публикации представлены в формате camelCase и сериализуются внутри в параметры snake_case, ожидаемые Threads

• Поддержка многоэтапной публикации каруселей

• Общий клиентский уровень для повторных попыток, опроса, пагинации и нормализованных ошибок Meta API

Быстрый старт

1. Установите зависимости:

npm install

2. Соберите сервер:

npm run build

3. Создайте файл локальной среды и установите как минимум THREADS_ACCESS_TOKEN.

4. Если вам все еще нужен токен, запустите локальный помощник OAuth:

npm run auth:token

5. Запустите сервер:

node dist/index.js

6. Вызовите validate_setup перед использованием потоков публикации или модерации для реальной учетной записи.

Каталог инструментов

Аутентификация

• exchange_code_for_token

• get_long_lived_access_token

• refresh_access_token

• get_app_access_token

Профили и поиск

• get_me

• get_profile

• get_profile_threads

Публикация и жизненный цикл

• get_publishing_limit

• create_thread_container

• publish_thread

• create_and_publish_thread

• repost_thread

• delete_thread

Чтение и ответы

• get_threads

• get_thread

• get_replies

• get_thread_conversation

• get_pending_replies

• manage_reply

• manage_pending_reply

Аналитика, поиск и встраивание

• get_user_insights

• get_thread_insights

• search_threads

• get_mentions

• get_oembed

Локации и диагностика

• search_locations

• get_location

• validate_setup

Явно вне области применения v1

• Вебхуки

• Хостинг встроенных обратных вызовов OAuth

• Любые недокументированные резервные конечные точки или вспомогательные функции, не охваченные официальной документацией или официальной коллекцией Postman

Архитектура

Сервер разделен на несколько четких уровней:

• src/index.ts запускает транспорт MCP stdio.

• src/threads/client.ts отвечает за аутентифицированные HTTP-вызовы, повторные попытки, пагинацию, опрос и нормализованные ошибки Meta API.

• src/tools/ содержит по одному модулю для каждого семейства инструментов плюс общие схемы.

Модель входных данных для публикации представлена как единое публичное дискриминантное объединение, охватывающее text, image, video, carousel и reply.

Предварительные требования

Вам необходимо выполнить все следующее, прежде чем сервер сможет совершать реальные вызовы API:

• Приложение Meta, настроенное для использования Threads

• Токен доступа пользователя Threads для учетной записи, с которой вы хотите работать

• Расширенный доступ и проверка приложения, если ваша интеграция этого требует

• Node.js 20+ на машине, где будет работать сервер

Переменные среды

Требуются для большинства инструментов, использующих токен пользователя:

• THREADS_ACCESS_TOKEN

Опционально:

• 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

Скопируйте .env.example и установите хотя бы токен доступа. THREADS_APP_ID и THREADS_APP_SECRET также необходимы для инструментов-помощников аутентификации и для get_oembed, если вы не передаете явный токен доступа приложения.

Где получить THREADS_APP_ID

• Откройте свое приложение на панели управления Meta for Developers: https://developers.facebook.com/apps/

• Откройте приложение, созданное с использованием Threads

• Перейдите в Use Cases -> Threads -> Customize -> Settings

• Скопируйте Threads App ID с этой страницы

• Используйте это значение как THREADS_APP_ID

Важно:

• Не используйте общий ID приложения Meta с главной панели управления или страницы настроек

• Используйте учетные данные, специфичные для варианта использования Threads, из Use Cases -> Threads -> Customize -> Settings

THREADS_APP_SECRET берется с той же страницы настроек Threads. Держите его в секрете.

Скрипт-помощник для токенов

Репозиторий включает локальный помощник OAuth, который следует потоку получения токена доступа Meta Threads:

1. Откройте окно авторизации Threads

2. Получите код авторизации по локальному URL обратного вызова

3. Обменяйте его на краткосрочный токен

4. Обменяйте его на долгосрочный токен

5. Сохраните результат в .env как THREADS_ACCESS_TOKEN

Настройка:

• Добавьте учетные данные вашего приложения Meta в .env

• Убедитесь, что действительный URI перенаправления OAuth вашего приложения совпадает с THREADS_REDIRECT_URI

Запуск:

npm run auth:token

Опциональные флаги:

• --redirect-uri http://127.0.0.1:8788/callback

• --env-file .env.local

• --no-open

Требуемые области доступа (scopes) по семействам инструментов

• threads_basic Используется get_me, get_profile, get_threads, get_thread и базовой проверкой настройки.

• threads_content_publish Используется get_publishing_limit, create_thread_container, publish_thread и create_and_publish_thread.

• threads_read_replies Используется get_replies и безопасными проверками чтения ответов в validate_setup.

• threads_manage_replies Используется manage_reply.

• threads_manage_insights Используется get_user_insights и get_thread_insights.

• threads_keyword_search Используется search_threads.

• threads_profile_discovery Используется get_profile и get_profile_threads для сценариев поиска публичных аккаунтов.

• threads_location_tagging Используется search_locations, get_location и потоками публикации, которые устанавливают locationId.

• threads_delete Используется delete_thread.

validate_setup выполняет безопасные проверки для определения доступа к threads_basic, threads_content_publish, threads_read_replies, threads_manage_insights, threads_keyword_search, threads_profile_discovery и threads_location_tagging. Он намеренно не выполняет деструктивные проверки для threads_manage_replies или threads_delete, поэтому эти области доступа активно не проверяются при настройке.

Поведение при публикации

Сервер моделирует официальные параметры контейнера в camelCase и сериализует их внутри в параметры snake_case, ожидаемые API Threads.

Поддерживаемые входные данные включают:

• Общие поля: text, replyControl, replyToId, quotePostId, topicTag, locationId, textEntities, allowlistedCountryCodes

• Поля только для текста: linkAttachment, pollAttachment, textAttachment, gifAttachment, enableReplyApprovals, autoPublishText, isGhostPost

• Поля для изображений или видео: imageUrl, videoUrl, altText, isSpoilerMedia

• Элементы карусели: проверенные массивы элементов изображений или видео с полями медиа для каждого элемента

Публикация карусели следует официальному многоэтапному потоку:

1. Создайте один контейнер элемента для каждого изображения или видео с is_carousel_item=true

2. Создайте родительский контейнер карусели с children=[...]

3. Опубликуйте родительский контейнер

Примечания по покрытию

Репозиторий в настоящее время охватывает следующие официальные семейства API Threads:

• Помощники авторизации

• Публикация, включая цитирование постов, публикацию репостов и опрос статуса контейнера

• Поиск профиля пользователя и получение постов публичного профиля

• Получение медиа Threads

• Получение ответов, выровненные беседы, ожидающие ответы, скрытие и отображение, а также потоки одобрения и игнорирования

• Аналитика пользователей и постов

• Поиск по ключевым словам и упоминания

• Поиск локаций и получение локации

• oEmbed

• Диагностика настройки

Пример локальной конфигурации MCP

Пример конфигурации в стиле Claude Desktop:

{
  "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"
      }
    }
  }
}

Если вы позже опубликуете этот пакет как CLI, command может стать threads-mcp.

Публикация

Метаданные пакета уже настроены для публикации в npm как публичный пакет:

• имя пакета: threads-mcp

• текущая версия: 0.0.0

• точка входа CLI: threads-mcp

• доступ к публикации: public

Перед публикацией выполните:

npm run build
npm test
npm publish --access public

prepublishOnly настроен на автоматический запуск этапов сборки и тестирования во время npm publish.

Разработка

Установите зависимости, как только Node.js станет доступен:

npm install
npm run build
npm test

Рекомендуемые ручные проверки:

1. Запустите npm run build для проверки компиляции TypeScript.

2. Запустите npm test для выполнения тестов схемы, клиента и регистрации инструментов.

3. Запустите сервер с помощью node dist/index.js.

4. Сначала вызовите validate_setup с реальным токеном.

5. Протестируйте create_thread_container и publish_thread с тестовой учетной записью Threads.

Известные ограничения

• Транспорт только stdio в v1

• Нет встроенного сервера обратного вызова OAuth; помощники обмена токенами вместо этого представлены как инструменты MCP

• validate_setup не может безопасно проверить threads_manage_replies без выполнения вызова модерации, изменяющего состояние

• validate_setup также не выполняет проверку удаления, изменяющую состояние

• create_and_publish_thread намеренно отклоняет autoPublishText=true, так как этот флаг конфликтует с явным двухэтапным контрактом инструмента

• Публикация ответов моделируется как выделенный вариант reply, поддерживаемый официальным параметром reply_to_id, и в настоящее время нацелена на текстовые ответы в публичной схеме

• Проверка поведения реального API по-прежнему зависит от действительных учетных данных приложения, одобренных областей доступа и реальной учетной записи Threads

Источники, использованные для выбора области API и конечных точек

• Справочник Meta Threads API: https://developers.facebook.com/docs/threads/reference

• Справочник по публикации Meta Threads: https://developers.facebook.com/docs/threads/reference/publishing

• Официальное рабочее пространство Meta Postman: https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api