Twitter/X MCP

Twitter/X MCP позволяет MCP-клиенту читать публичные посты X, ответы и профили, а также выполнять поиск по X. По умолчанию используется Rettiwt, поэтому план разработчика X не нужен. Если у вас есть доступ, можно переключиться на официальное X API.

Требования

• Node.js 22.21.0 или новее в рамках линейки Node 22. Текущий релиз Rettiwt не поддерживает Node 23 или более новые версии.

• Необходим ключ RETTIWT_API_KEY. Учётные данные официального X API работают, если выбран режим API.

Related MCP server: MCP Twitter/X Server

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

После публикации пакета ваш MCP-клиент сможет запускать его без клонирования репозитория:

npx -y @granitebps/twitter-mcp

Сервер выбирает Rettiwt, если не указан TWITTER_MODE. Передайте RETTIWT_API_KEY в конфигурации клиента.

Сервер использует stdio. Оставьте stdout свободным для MCP-трафика.

Запуск из клонированного репозитория

Для разработки сервера или использования клона напрямую:

git clone https://github.com/granitebps/twitter-mcp.git
cd twitter-mcp
npm ci
npm run build

Направьте MCP-клиент на скомпилированную точку входа:

node /absolute/path/to/twitter-mcp/dist/cli.js

Выполняйте npm run build после каждого изменения исходного кода. Не используйте src или npm run dev в качестве stdio-команды клиента. Логи сборки в stdout могут повредить MCP-сообщения.

Конфигурация клиента

Каждый пример начинается с npm-пакета, за которым следует локальный аналог. Замените /absolute/path/to/twitter-mcp на путь к вашему клону и your_key_here — на ваш ключ Rettiwt. Не помещайте в коммит файл конфигурации, содержащий ключ.

Claude

Добавьте npm-пакет в Claude Code:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- npx -y @granitebps/twitter-mcp

Для локальной сборки:

claude mcp add twitter --env RETTIWT_API_KEY=your_key_here -- node /absolute/path/to/twitter-mcp/dist/cli.js

Claude Code по умолчанию использует локальную область видимости. Добавьте --scope user перед twitter, чтобы сервер был доступен во всех проектах.

Claude Desktop считывает тот же сервер из claude_desktop_config.json. Перезапустите приложение после изменения файла.

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

Для локальной сборки замените command и args на:

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Codex

Добавьте npm-пакет в ~/.codex/config.toml или в .codex/config.toml в доверенном проекте:

[mcp_servers.twitter]
command = "npx"
args = ["-y", "@granitebps/twitter-mcp"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

Для локальной сборки:

[mcp_servers.twitter]
command = "node"
args = ["/absolute/path/to/twitter-mcp/dist/cli.js"]

[mcp_servers.twitter.env]
RETTIWT_API_KEY = "your_key_here"

Перезапустите Codex после изменения файла. CLI, расширение IDE и настольное приложение используют эту конфигурацию на одном компьютере.

OpenCode

Добавьте npm-пакет в opencode.json или opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "twitter": {
      "type": "local",
      "command": ["npx", "-y", "@granitebps/twitter-mcp"],
      "enabled": true,
      "environment": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

Для локальной сборки замените массив command на:

{
  "command": ["node", "/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Cursor

Добавьте npm-пакет в .cursor/mcp.json в проекте или в ~/.cursor/mcp.json для глобального использования:

{
  "mcpServers": {
    "twitter": {
      "command": "npx",
      "args": ["-y", "@granitebps/twitter-mcp"],
      "env": {
        "RETTIWT_API_KEY": "your_key_here"
      }
    }
  }
}

Для локальной сборки замените command и args на:

{
  "command": "node",
  "args": ["/absolute/path/to/twitter-mcp/dist/cli.js"]
}

Провайдеры

Настройка Rettiwt

На этом сервере Rettiwt требует аутентифицированного пользовательского режима. Гостевой режим не поддерживается.

1. Сформируйте ключ API по инструкциям по аутентификации Rettiwt.

2. Сохраните его как RETTIWT_API_KEY в окружении MCP-клиента.

3. Запустите сервер без TWITTER_MODE или явно укажите TWITTER_MODE=rettiwt.

Ключ Rettiwt содержит cookie-сессии X и предоставляет тот же доступ, что и аккаунт. Обращайтесь с ним как с паролем. Не сохраняйте его в коммит, не вставляйте в issue, не записывайте в логи и не передавайте через аргументы командной строки. Используйте ключ только для аккаунта, которым вы владеете или разрешением на доступ к которому обладаете.

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

Настройка официального X API

Используйте Bearer-токен:

TWITTER_MODE=api
TWITTER_BEARER_TOKEN=your_bearer_token

Или предоставьте полный набор настроек OAuth:

TWITTER_MODE=api
TWITTER_API_KEY=your_api_key
TWITTER_API_SECRET=your_api_secret
TWITTER_ACCESS_TOKEN=your_access_token
TWITTER_ACCESS_SECRET=your_access_secret

Учётные данные создаются в портале разработчика X. X контролирует доступ к API и цены, поэтому перед выбором этого режима изучите актуальные условия.

Конфигурация

Сервер отклоняет неполную конфигурацию OAuth при запуске. Он читает учётные данные из окружения процесса и никогда не возвращает их через get_server_info.

Инструменты

max_results по умолчанию равно 10 и принимает значения от 1 до 100. Успешные вызовы возвращают структурированный контент MCP и JSON-текст для устаревших клиентов. Инструменты возврата коллекций отдают элементы как JSON-текст, а курсоры и предупреждения размещают в структурированном контенте.

Ошибки

Вызовы инструментов используют стабильные коды ошибок:

• INVALID_INPUT

• AUTH_REQUIRED

• AUTH_FAILED

• NOT_FOUND

• RATE_LIMITED

• UPSTREAM_UNAVAILABLE

• TIMEOUT

• UNSUPPORTED_OPERATION

• INTERNAL_ERROR

В ошибках указывается провайдер и сообщается, стоит ли повторить попытку. В них не включаются учётные данные и необработанные тела ответов вышестоящего сервиса.

Архитектура

stdio CLI
  -> validated environment configuration
  -> MCP server and tool handlers
  -> TwitterProvider contract
       -> Rettiwt adapter
       -> official X API adapter

Доменные схемы не зависят от конкретного провайдера. Каждый адаптер провайдера отображает данные вышестоящего сервиса, соблюдает лимиты и тайм-ауты и переводит ошибки. Импорт src/index.ts не запускает сервер.

Разработка

npm ci
npm run check

npm run check проверяет форматирование, стиль кода, типы, покрытие, тесты продакшн-сборки, содержимое npm-пакета и чистую установку из тарбалла. Штатный тестовый набор использует заглушки и не требует учётных данных X.

Полезные точечные команды:

npm test
npm run typecheck
npm run lint
npm run build
npm run check:package
npm run check:install
npx @modelcontextprotocol/inspector node dist/cli.js

Живой смоук-тест Rettiwt

Живой смоук-тест запускает скомпилированный stdio-сервер и вызывает get_tweet, get_tweet_replies, get_user_profile и search_tweets. Имя пользователя и поисковый запрос берутся из выбранной записи.

RETTIWT_API_KEY=your_key_here \
TWITTER_LIVE_TWEET_ID=1234567890123456789 \
npm run test:live

Выбирайте общедоступную запись, чей профиль автора всё ещё доступен. Если хотя бы одной из переменных нет, команда останавливается до запуска живого сервера или выполнения сетевого запроса. Он не выполняется в рамках npm run check и в обычном CI.

Проверка релиза

Автоматизированный набор охватывает конфигурацию, адаптеры провайдеров, вызовы MCP, скомпилированную stdio-точку входа и установку из npm-тарбалла. Живой смоук-тест Rettiwt необязателен и не выполняется в обычном CI. Версия 1.0.0 была подготовлена без прямой проверки вышестоящего сервиса.

Поддерживающие могут следовать руководству по выпуску для ручного процесса публикации в npm, MCP Registry и GitHub. Живые тесты должны читать учётные данные из секретов репозитория и не должны выполняться для недоверенных pull request.

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

Отсутствует ключ Rettiwt

Если при запуске выводится RETTIWT_API_KEY is required in rettiwt mode, задайте ключ в конфигурации MCP-клиента. Настольные клиенты не наследуют автоматически файл .env из оболочки.

Неверная аутентификация Rettiwt

При появлении Invalid authentication data или AUTH_FAILED создайте новый ключ Rettiwt и проверьте, что сессия X всё ещё работает. Не размещайте ошибочный ключ в issue.

Ограничение частоты запросов

Прикоде RATE_LIMITED подождите перед повторной попыткой и снизьте частоту запросов. Проверяйте retryAfterSeconds, когда провайдер передаёт это значение.

Официальный API 401 или 403

Проверьте набор учётных данных, разрешения приложения, доступ к конечной точке и актуальный тарифный план X API.

Message: Node engine warning

Предупреждение о версии Node.js

Запускайте Node.js 22.21.0 или более новую версию Node 22. Не используйте Node 23 или новее с текущей зависимостью Rettiwt.

Лицензия

ISC