threads-mcp

MCP-сервер для Threads API. Он занимается только платформенным вводом-выводом: публикация поста, чтение собственных постов, чтение их статистики, проверка квоты публикаций. Никакой редакционной логики, никакого планирования, никаких мнений о том, что вам писать.

Это тот компонент, который нужен агенту, чтобы достучаться до Threads. Что публиковать — ваша проблема.

npx -y @andreaselmi/threads-mcp    # needs THREADS_ACCESS_TOKEN in the environment

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

• Инструменты

• Получение токена доступа

• Подключение к клиенту

• Устранение неполадок

• Чего он намеренно не делает

• Разработка

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

Требуется Node 20 или новее. Устанавливать ничего не нужно: MCP-клиенты запускают сервер через npx, который загружает его при первом использовании.

1. Получите долгоживущий токен доступа — полное руководство ниже. Это единственное по-настоящему хлопотное место, и это вина Meta, а не этого пакета.

2. Экспортируйте его в оболочке, из которой вы запускаете свой MCP-клиент:

   export THREADS_ACCESS_TOKEN="THQ..."

3. Добавьте сервер в MCP-конфигурацию вашего клиента:

   {
     "mcpServers": {
       "threads": {
         "command": "npx",
         "args": ["-y", "@andreaselmi/threads-mcp"]
       }
     }
   }

4. Перезапустите клиента и спросите его, кто вы. Он должен вызвать threads_whoami и ответить вашим именем ползователя.

Чтобы проверить, что сервер работает, вообще не подключая клиента:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y @andreaselmi/threads-mcp

Строка JSON с именем threads-mcp означает, что он запустился и прочитал ваш токен. Сообщение об ошибке на stderr подскажет, чего не хватает.

Related MCP server: meta-threads-mcp

Инструменты

Два инструмента публикации помечены как destructiveHint: true; все остальное — readOnlyHint. Клиенты, которые запрашивают подтверждение перед деструтивными инструментами, спросят и перед этими — и правильно: опубликованный пост сразу становится доступным, и API не может его редактировать или удалить. Удаление поста означает открытие приложения Threads.

threads_post_insights читает статистику только ваших собственных постов и требует область доступа threads_manage_insights. threads_publishing_limit сообщает о скользящей суточной квоте — по умолчанию 250 постов на аккаунт.

Почему существует threads_publish_container

Публикация в Threads — это два вызова: создать контейнер, затем опубликовать его. Если второй вызов не удается, контейнер все равно существует и остается действительным в течение 24 часов — повтор всей операции привел бы к двойной публикации одного и того же текста. При сбое публикации этот сервер помещает id контейнера в сообщение об ошибке; передайте его в threads_publish_container, чтобы завершить дело ровно один раз.

Сервер также ждет, пока контейнер не достигнет состояния FINISHED, прежде чем публиковать его, опрашивая каждые 2 секунды до минуты, чтобы медленный контейнер не был принят за сбой.

Получение токена доступа

Процедура Meta состоит из четырех шагов, и сокращения нет. В первый раз заложите пятнадцать минут.

1. Создайте приложение

Перейдите на developers.facebook.com/apps и создайте приложение с вариантом использования Threads. Панель управления генерирует два набора учетных данных — используйте специфичные для Threads идентификатор приложения и секрет, а не Facebook-овские. На этом спотыкаются почти все.

2. Добавьте области доступа и тестировщика

В разделе варианта использования Threads добавьте нужные области доступа (scopes):

Затем добавьте свой аккаунт Threads как тестировщика и примите приглашение в настройках этого аккаунта (Аккаунт → Разрешения для сайтов → Приглашения). Пока приглашение не принято, каждий вызов завершается ошибкой разрешений, которая никогда не упоминает приглашение.

3. Получите кратковременный токен

Откройте окно авторизации в браузере, заменив плейсхолдеры:

https://threads.net/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code

Подтвердите, и вы попадете на ваш redirect_uri с добавленным ?code=.... Redirect URI должен точно совпадать с одним из зарегистрированных в настройках приложения. Скопируйте код — он одноразовый и истекает через несколько минут — и обменяйте его:

curl -X POST https://graph.threads.net/oauth/access_token \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=THE_CODE_FROM_THE_REDIRECT

Это возвращает кратковременный токен, действительный в течение одного часа. Не останавливайтесь здесь.

4. Обменяйте его на долгоживущий токен

curl -G https://graph.threads.net/access_token \
  -d grant_type=th_exchange_token \
  -d client_secret=YOUR_APP_SECRET \
  -d access_token=THE_SHORT_LIVED_TOKEN

Резултат действителен в течение 60 дней. Это значение для THREADS_ACCESS_TOKEN.

Продление срока действия

Долгоживущий токен можно обновить, когда ему исполнется не менее 24 часов и до истечения срока действия. Кажое обновление дает еще 60 дней:

curl -G https://graph.threads.net/refresh_access_token \
  -d grant_type=th_refresh_token \
  -d access_token=YOUR_LONG_LIVED_TOKEN

Токен, не использованный в течение 60 дней, истекает, и его нельзя обновить — придется начать с шага 3. Поставьте напоминание в календаре; ничто вас не предупредит.

Подключение к клиенту

Переменные окружения

Токен читается из окружения при запуске и нигде не записывается — ни в файл, ни в строку журнала. Предпочитайте экспортировать его в оболочке, а не записывать в конфигурационный файл: конфигурационные файлы попадают в коммиты, а экспорт в оболочке — нет.

Claude Code

claude mcp add threads --scope user -- npx -y @andreaselmi/threads-mcp

Или закоммитьте .mcp.json в корне проекта, чтобы каждий, кто работает над ним, получил сервер:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp@^0.1.0"]
    }
  }
}

Фиксация ^0.1.0 подхватит исправления, но не будущую мажорную версию, которая меняет инструменты. Проверьте подключение с помощью /mcp.

Claude Desktop, Cursor и другие клиенты

Та же форма, в конфигурационном файле соответствующего клиента: claude_desktop_config.json для Claude Desktop, ~/.cursor/mcp.json для Cursor. Клиентам, которые не наследуют окружение вашей оболочки, нужен токен, переданный явно:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"],
      "env": { "THREADS_ACCESS_TOKEN": "THQ..." }
    }
  }
}

Если вы так сделаете, этот файл теперь содержит живой учетный данны: держите его вне контроля версий.

Установка вместо этого

Если вы предпочитаете не проходить через npx при кажом запуске:

npm install -g @andreaselmi/threads-mcp

то используйте "command": "threads-mcp" без args.

Устранение неполадок

Сервер не запускается / клиент показывает CONNECTION_CLOSED. Процесс завершился при запуске, почти всегда из-за того, что THREADS_ACCESS_TOKEN не установлен в окружении, из которого был запущен клиент. Экспорт в теринале не достянет до уже работающео приложения или до приложения, запущенного из Dock. Запустите сервер вручную, чтобы увидеть настоящее сообщение:

npx -y @andreaselmi/threads-mcp

Он выводит причину и завершает работу.

Invalid OAuth access token или подобное. Токен истек (60 дней), или вы все еще используете кратковременный из шага 3. Повторите шаг 4.

Ошибка разрешений при вызове, который должен работать. Либо отсутствует область доступа — для статистики и публикации нужна своя — либо приглашение тестировщика так и не было принято в настройках аккаунта Threads.

Post is N characters, the Threads limit is 500. Это сообщение формирует этот сервер до отправки любого запроса, так что ничего не было опубликовано. Разделите текст.

Публикация не удалась, и вы не уверены, ушла ли она. Прочитайте ошибку: если в ней указан id контейнера, значит контейнер существует, и пост не был опубликован. Вызовите threads_publish_container с этим id, а не публикуйте заново. Если id не указан, проверьте threads_list_posts перед повторной попыткой.

Квота исчерпана. threads_publishing_limit показывает скользящее окно в 24 часа — 250 постов на аккаунт. Когда оно исчерпано, ничто не публикуется, пока посты не выйдут из окна.

Чего он намеренно не делает

Только текстовые посты — никаких изображений, видео, каруселей или вложенных ссылок. Он читает ваши собственные посты, а не ответы, упоминания или чужой контент. Он не планирует публикации, не повторяет по таймеру и не хранит состояние между вызвами: у него нет базы данны, и он ничего не запоминает.

Он также ничего не знает о том, что вы публикуете. Здесь нет ни тем, ни тона голоса, ни редакционны правил — это относится к тому, кто его вызвает. Пул-реквесты, добавляющие специфичное для продукта поведение, попросят перенести его в вызывающий код.

Разработка

npm install
npm test          # vitest, no network: fetch is stubbed
npm run dev       # run the server from source over stdio
npm run build     # tsc to dist/

Кажый тест работает с фейковым fetch, так что набор тестов никог да не касается настоящего API, и ему не нужен токен. Проблемы и пул-реквесты: github.com/andreaselmi/threads-mcp.

Лицензия

MIT