X MCP Server

Сервер Model Context Protocol (MCP) на TypeScript для официального X API.

Этот проект позволяет MCP-совместимым агентам, включая агентов ChatGPT, безопасно читать из учетных записей X и публиковать в них через локальный сервер, работающий на вашем компьютере.

Сервер поддерживает:

• Чтение аутентифицированной учетной записи X.

• Поиск пользователей X по имени пользователя.

• Чтение постов по идентификатору.

• Список последних постов пользователя.

• Поиск последних постов с использованием синтаксиса поиска X.

• Создание постов и ответов, когда режим записи явно включен.

• Выбор отдельной учетной записи X для каждой локальной установки на компьютере.

• Работа через stdio для локальных MCP-хостов.

• Работа через локальный Streamable HTTP для ChatGPT через OpenAI Secure MCP Tunnels.

Статус проекта

Это функциональный MVP.

Реализовано:

• MCP-сервер через stdio.

• MCP-сервер через Streamable HTTP.

• Клиент официального X API.

• Локальная конфигурация с несколькими учетными записями.

• Безопасный режим read-only по умолчанию.

• Явный режим read-write для публикации и ответов.

• Локальный помощник OAuth 2.0 Authorization Code + PKCE для повторной авторизации учетной записи X.

• Модульные тесты с использованием Vitest.

• Руководство по подключению ChatGPT через OpenAI Secure MCP Tunnels.

• Руководство по жизненному циклу локального сервера для ручного и автоматического запуска в Windows.

Related MCP server: X API FastMCP Server

Как это работает

Для локальных MCP-хостов:

MCP host
  -> stdio
  -> x-mcp-server
  -> official X API

Для агентов ChatGPT:

ChatGPT agent
  -> custom MCP app
  -> OpenAI Secure MCP Tunnel
  -> tunnel-client on your computer
  -> http://127.0.0.1:3001/mcp
  -> x-mcp-server
  -> official X API

Учетные данные X остаются локальными. ChatGPT подключается к локальному MCP-серверу через туннель; он не получает ваши токены доступа X.

Доступные MCP-инструменты

Инструменты записи блокируются, если не задано X_MCP_MODE=read-write.

Требования

• Node.js 20 или новее.

• Учетная запись X Developer.

• Приложение X Developer с включенным OAuth 2.0.

• Области чтения X: tweet.read users.read.

• Область записи X для публикации и ответов: tweet.write.

• Рекомендуемая область обновления X: offline.access.

• Для ChatGPT: включенный режим разработчика.

• Для локальных подключений ChatGPT: OpenAI Secure MCP Tunnel и tunnel-client.

Пошаговая установка

1. Клонирование репозитория

git clone https://github.com/lluisfont/x-mcp-server.git
cd x-mcp-server

Если у вас уже есть репозиторий:

cd C:\Repos\x-mcp-server
git pull

2. Установка зависимостей

npm install

3. Создание локального файла окружения

Copy-Item .env.example .env

Отредактируйте .env локально.

Не коммитьте .env. Он может содержать токены доступа, токены обновления, секреты клиента и закрытые ключи API.

4. Настройка активной учетной записи X

Для именованной локальной учетной записи:

X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only
X_API_BASE_URL=https://api.x.com

X_ACCOUNT_FCBNEWS2026_USER_ACCESS_TOKEN=
X_ACCOUNT_FCBNEWS2026_REFRESH_TOKEN=

Для нескольких учетных записей на одном компьютере:

X_MCP_ACCOUNT=fcbnews2026
X_MCP_MODE=read-only

X_ACCOUNT_FCBNEWS2026_USER_ACCESS_TOKEN=
X_ACCOUNT_FCBNEWS2026_REFRESH_TOKEN=

X_ACCOUNT_LLUISFONT_USER_ACCESS_TOKEN=
X_ACCOUNT_LLUISFONT_REFRESH_TOKEN=

X_MCP_ACCOUNT выбирает локальный профиль, используемый этой установкой. Разные компьютеры могут выбирать разные учетные записи без изменения кода.

Также поддерживается устаревший режим одной учетной записи:

X_MCP_ACCOUNT=default
X_USER_ACCESS_TOKEN=

Новые установки должны использовать именованные учетные записи.

5. Выбор транспорта

Для локальных MCP-хостов, которые запускают процесс напрямую:

X_MCP_TRANSPORT=stdio

Для ChatGPT через локальный туннель:

X_MCP_TRANSPORT=http
X_MCP_HTTP_PORT=3001
X_MCP_HTTP_PATH=/mcp

6. Запуск проверки типов и тестов

npm run typecheck
npm test
npm run build

7. Запуск MCP-сервера

Для stdio:

npm run dev

Для локального HTTP:

npm run dev:http

Конечная точка HTTP MCP по умолчанию:

http://127.0.0.1:3001/mcp

Проверка работоспособности:

Invoke-RestMethod http://127.0.0.1:3001/healthz | ConvertTo-Json -Compress

Ожидаемый ответ:

{"ok":true,"transport":"http","activeAccount":"fcbnews2026","mode":"read-only"}

Жизненный цикл локального MCP-сервера

Когда ChatGPT использует этот MCP через туннель, должны быть запущены два локальных процесса:

1. The MCP HTTP server
   -> npm run dev:http
   -> http://127.0.0.1:3001/mcp

2. tunnel-client
   -> .\.tools\tunnel-client\tunnel-client.exe run --profile <profile>
   -> OpenAI Secure MCP Tunnel

Если любой из процессов остановлен, ChatGPT не сможет использовать MCP-инструменты.

Запуск вручную

Терминал 1:

cd C:\Repos\x-mcp-server
npm run dev:http

Терминал 2:

cd C:\Repos\x-mcp-server
.\.tools\tunnel-client\tunnel-client.exe run --profile x-fcbnews

Держите оба терминала открытыми.

Проверка локальной доступности

Проверьте MCP-сервер:

Invoke-RestMethod http://127.0.0.1:3001/healthz | ConvertTo-Json -Compress

Проверьте туннельный клиент:

Invoke-WebRequest http://127.0.0.1:8080/readyz -UseBasicParsing

Конечная точка готовности туннеля должна возвращать HTTP 200.

Остановка вручную

Нажмите Ctrl+C в:

• Терминале, в котором выполняется npm run dev:http.

• Терминале, в котором выполняется tunnel-client run.

Когда оба процесса остановлены, ChatGPT больше не имеет доступа к локальному MCP-серверу.

Смена учетной записи или режима безопасности

Отредактируйте .env.

Смените активную учетную запись:

X_MCP_ACCOUNT=fcbnews2026

Включите режим записи:

X_MCP_MODE=read-write

Вернитесь в безопасный режим только для чтения:

X_MCP_MODE=read-only

Перезапустите MCP HTTP-сервер после изменения .env:

Ctrl+C
npm run dev:http

Туннель может оставаться запущенным, если локальный порт и путь MCP не изменились.

Автоматический запуск при входе в Windows

Для компьютера, который должен регулярно размещать этот MCP, используйте Планировщик заданий Windows.

Создайте локальный скрипт запуска, например:

C:\Users\<user>\mcp-start\x-fcbnews-start.ps1

Скрипт:

$repo = "C:\Repos\x-mcp-server"
$profile = "x-fcbnews"

Set-Location $repo

Start-Process powershell.exe -ArgumentList @(
  "-NoExit",
  "-ExecutionPolicy", "Bypass",
  "-Command", "cd `"$repo`"; npm run dev:http"
) -WindowStyle Minimized

Start-Sleep -Seconds 5

Start-Process powershell.exe -ArgumentList @(
  "-NoExit",
  "-ExecutionPolicy", "Bypass",
  "-Command", "cd `"$repo`"; .\.tools\tunnel-client\tunnel-client.exe run --profile $profile"
) -WindowStyle Minimized

Зарегистрируйте запланированное задание:

$action = New-ScheduledTaskAction `
  -Execute "powershell.exe" `
  -Argument "-ExecutionPolicy Bypass -File `"C:\Users\<user>\mcp-start\x-fcbnews-start.ps1`""

$trigger = New-ScheduledTaskTrigger -AtLogOn

Register-ScheduledTask `
  -TaskName "X MCP FCBNews2026" `
  -Action $action `
  -Trigger $trigger `
  -Description "Starts the local X MCP server and OpenAI tunnel-client at Windows logon."

Отключите автоматический запуск:

Disable-ScheduledTask -TaskName "X MCP FCBNews2026"

Включите его снова:

Enable-ScheduledTask -TaskName "X MCP FCBNews2026"

Удалите его:

Unregister-ScheduledTask -TaskName "X MCP FCBNews2026" -Confirm:$false

Полное руководство по жизненному циклу:

docs/local-server-lifecycle.md

Подключение к ChatGPT

Общая схема:

1. Run the MCP server over local HTTP.
2. Create a tunnel in OpenAI Platform.
3. Create a local tunnel-client profile pointing to http://127.0.0.1:3001/mcp.
4. Start tunnel-client.
5. Create a custom MCP app in the ChatGPT agent using Connection: Tunnel.
6. Test x_get_active_account or x_get_me before any write operation.

Рекомендуемые настройки пользовательского MCP для ChatGPT:

Connection: Tunnel
Tunnel: <your OpenAI tunnel>
Authentication: No authentication

Используйте No authentication, когда MCP-сервер управляет конечными учетными данными сервиса локально, например через .env.

Полное руководство по настройке ChatGPT:

docs/chatgpt-mcp-setup.md

Повторная авторизация учетной записи X

В X Developer настройте приложение:

OAuth 2.0: Enabled
App permissions: Read and write
Callback URI: http://127.0.0.1:3002/callback
Website URL: http://127.0.0.1:3002

Выполните:

$env:X_OAUTH_CLIENT_ID = "<OAuth 2.0 Client ID>"
$env:X_MCP_ACCOUNT = "fcbnews2026"
npm run x:oauth

Откройте сгенерированный URL, будучи авторизованным в нужной учетной записи X. После авторизации помощник обновит .env, добавив токен выбранной учетной записи.

Перезапустите MCP-сервер после повторной авторизации:

npm run dev:http

Затем проверьте с помощью:

x_get_active_account

Подробное руководство по OAuth:

docs/x-oauth.md

Модель безопасности

Сервер по умолчанию запускается в режиме только для чтения:

X_MCP_MODE=read-only

Инструменты записи требуют:

X_MCP_MODE=read-write

Перед публикацией:

• Проверьте активную учетную запись с помощью x_get_active_account.

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

• Убедитесь, что токен X имеет область tweet.write.

• Попросите агента вернуть сгенерированный post_id.

• Не считайте пост опубликованным, пока X не вернет идентификатор.

Скрипты

Документация

• docs/project-architecture.md: архитектура проекта.

• docs/configuration.md: переменные окружения и настройка нескольких учетных записей.

• docs/local-server-lifecycle.md: запуск, остановка и автоматизация локального MCP-сервера.

• docs/tools.md: MCP-инструменты и контракты использования.

• docs/x-oauth.md: повторная авторизация X OAuth.

• docs/development.md: рекомендации по разработке, тестированию и внесению изменений.

• docs/chatgpt-mcp-setup.md: пошаговая настройка MCP для ChatGPT.

Операционная безопасность

• Храните учетные данные вне Git.

• Сохраняйте read-only в качестве режима по умолчанию.

• Включайте read-write только для контролируемых рабочих процессов.

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

• Не записывайте в журнал токены доступа или токены обновления.

• Не вставляйте токены в чаты, issues, документацию или пул-реквесты.

• Не используйте автоматический запуск в режиме read-write на компьютерах общего пользования.

Лицензия

Открытая лицензия еще не выбрана.