X Harnessの導入方法｜X Developer・公式CLI・MCP接続を順番に解説

X Harnessの構成、X Developer認証情報、Cloudflareへの導入、管理画面の初期確認、Codex・Claude CodeへのMCP接続を解説します。 Worker・D1・管理画面・X API・MCP・LINE連携の役割を、実装と対応させて把握します。 投稿・返信・DMに必要なOAuth 1.0a権限を、トークン生成前に正しく設定します。 再開可能なセットアップCLIで、Cloudflare構成とXアカウント登録を一続きで完了します。

この記事はHarness Academyの教材データを基に、各Harnessの公式リポジトリにある実装箇所と照合して構成しています。秘密情報や本番データを記事・AIチャットへ貼らず、外部送信は必ず検証対象を限定してください。

最初に確認すること

• X Harnessの全体像と、自動化の境界を理解する: X Harnessが何を保存し、どこでX APIを呼び、どの操作が課金・外部変更になるか説明できる
• X Developerの権限と4つの認証情報を準備する: 対象アカウント、X User ID、Consumer Key/Secret、Access Token/Secretを安全に準備できる
• 公式CLIでWorker・D1・管理画面を導入する: D1、Worker、Pages管理画面、Xアカウント、MCP設定が同じ環境へ接続された状態にする
• 管理画面・アカウント・自動機能を安全に初期確認する: 正しいWorkerとXアカウントへ接続し、自動機能OFFのまま読み取り確認ができる
• Codex／Claude CodeへX Harness MCPを接続する: AIエージェントが正しいX Harnessへ接続し、外部変更前に対象と操作を確認する

X Harnessの全体像と、自動化の境界を理解する

Worker・D1・管理画面・X API・MCP・LINE連携の役割を、実装と対応させて把握します。

この工程のゴール: X Harnessが何を保存し、どこでX APIを呼び、どの操作が課金・外部変更になるか説明できる

X Harnessは、Cloudflare WorkersのAPI、D1データベース、Next.js管理画面、TypeScript SDK、MCP、X APIラッパーで構成されるセルフホスト型の運用基盤です。管理画面とAIエージェントは同じWorker APIを利用します。

Cronでは予約投稿、エンゲージメントゲート、ステップ配信、フォロワー数スナップショットを処理します。自動機能は初期状態で無効です。特にX APIの読み取りは従量課金になり得るため、ローカルDB、無料収集、verify_onlyの順でAPI呼び出しを減らします。

手順

1. 構成を読む

apps/worker、apps/web、packages/db、x-sdk、sdk、mcp、create-x-harnessの責務を一枚にします。

2. データの流れを追う

管理画面またはMCPからWorker、D1、X APIへ到達する経路を確認します。

3. 自動処理を分ける

Cronで動くもの、利用者の操作でだけ動くもの、無料収集で代替できるものを分類します。

4. 外部変更を固定する

投稿、返信、DM、フォロー、公開、デプロイは実行前確認が必要な操作としてルール化します。

完了条件

• Worker・D1・管理画面・X API・MCPの関係が分かる
• Cron対象と手動対象を区別できる
• X API read/writeと無料収集の境界が明確
• 外部変更の実行前確認ルールが決まる

注意: 『OSS本体が無料』と『X API利用料がゼロ』は同じ意味ではありません。現在のX Developer料金と利用量は運用前に必ず確認します。

Academy教材: X Harnessを導入する / Lesson 17-1

X Developerの権限と4つの認証情報を準備する

投稿・返信・DMに必要なOAuth 1.0a権限を、トークン生成前に正しく設定します。

この工程のゴール: 対象アカウント、X User ID、Consumer Key/Secret、Access Token/Secretを安全に準備できる

現行コードの書き込み操作は、Consumer Key、Consumer Secret、Access Token、Access Token Secretを使うOAuth 1.0aに対応しています。投稿・返信・DMを使う場合、アクセストークン生成前にアプリ権限をRead, Write, and Direct Messagesへ設定します。

権限変更前に作ったトークンは新しい権限を持ちません。権限を変更した場合はトークンを再生成し、古いトークンを失効させます。認証情報はチャット、教材、Git、スクリーンショットへ貼りません。

手順

1. 用途を決める

対象を自社保有アカウントに限定し、投稿・返信・DM・分析の利用目的を記録します。

2. アプリ権限を先に設定

Read, Write, and Direct Messagesを選び、保存後にトークンを生成します。

3. IDを照合

@usernameと数字のX User IDが同じプロフィールを指すことを確認します。

4. 安全に入力

公式セットアップCLIの対話入力を使い、値を会話やcommitへ残しません。

完了条件

• アプリ権限をトークン生成前に設定している
• 6つの必要項目が揃っている
• 秘密値がチャット・Git・ログへ出ていない
• 対象アカウントと利用目的が明確

注意: Xの料金、審査、権限名称は変更される可能性があります。画面上の現在値を確認し、教材内の金額だけで購入判断しません。

Academy教材: X Harnessを導入する / Lesson 17-2

公式CLIでWorker・D1・管理画面を導入する

再開可能なセットアップCLIで、Cloudflare構成とXアカウント登録を一続きで完了します。

この工程のゴール: D1、Worker、Pages管理画面、Xアカウント、MCP設定が同じ環境へ接続された状態にする

create-x-harnessのsetupは依存関係、Cloudflare認証、X認証情報、D1、migration、Worker、Secrets、Xアカウント登録、Pages管理画面、callback、MCPを順に処理します。.x-harness-setup.jsonへ完了工程を保存し、中断後も再開します。

セットアップstateと.mcp.jsonには秘密値が入り得ます。作成後にGit追跡外であることを確認し、Worker URL、Admin URL、D1名、Cloudflare accountだけを秘密値なしの運用台帳へ残します。

手順

1. 事前点検

Node 20以上、pnpm、Git、Wrangler認証、Cloudflare accountを確認します。

2. 公式CLIを実行

mainのpackageとCLI実装を確認してからsetupを開始し、対話入力だけを本人が行います。

3. 自動工程を確認

D1、migration、Worker、Secrets、アカウント、Admin、callback、MCPの完了状態を照合します。

4. 秘密ファイルを隔離

.x-harness-setup.json、.mcp.json、環境ファイルが追跡されないことを検査します。

完了条件

• D1 migrationとWorker deployが成功
• 管理画面が正しいWorker URLを参照
• 対象Xアカウントが一件登録済み
• state・MCP・秘密ファイルがGit追跡外

注意: 既存の同名D1・Worker・Pagesを削除して作り直しません。まずsetup stateとCloudflare上の実物を照合します。

Academy教材: X Harnessを導入する / Lesson 17-3

管理画面・アカウント・自動機能を安全に初期確認する

ログイン、接続先、権限、アカウント切替、停止状態を確認し、まだ投稿せずに導入を検証します。

この工程のゴール: 正しいWorkerとXアカウントへ接続し、自動機能OFFのまま読み取り確認ができる

管理画面はAPIキーでWorkerへ接続し、選択中のXアカウントを各ページへ引き継ぎます。最初にAdmin URL、Worker URL、Cloudflare account、X usernameの対応表を作ると、別環境や別アカウントへの誤操作を防げます。

自動機能は設定画面のauto_features_enabledで制御されます。初回確認はOFFのまま行い、health、capabilities、登録アカウント、D1上の基本データだけを確認します。

手順

1. 4点を固定

Cloudflare account、Worker、Admin、X usernameを一行にします。

2. 接続を確認

health、capabilities、アカウント一覧をread-onlyで確認します。

3. 権限を確認

owner/admin/editor/viewerの役割と、自分のAPIキーの範囲を確認します。

4. 停止状態を確認

自動機能、ゲート、予約投稿、ステップ配信が意図せず動いていないことを確認します。

完了条件

• AdminとWorkerの組み合わせが正しい
• 対象Xアカウントが一意に選択される
• 自動機能がOFFまたは意図した状態
• 投稿・DMなしで導入状態を確認できる

Academy教材: X Harnessを導入する / Lesson 17-4

Codex／Claude CodeへX Harness MCPを接続する

API URLと個人キーを安全に登録し、最初は一覧取得だけで39ツールの接続を確認します。

この工程のゴール: AIエージェントが正しいX Harnessへ接続し、外部変更前に対象と操作を確認する

@x-harness/mcpは投稿、反応、ユーザー、DM、ゲート、ステップ、分析、スタッフ、キャンペーン、利用量、記事、無料収集、Growthのツール群を提供します。ツールが使えることと、自由に実行してよいことは別です。

最初はaccount_summary、list_engagement_gates、get_usage_summaryなどの読み取りだけを試します。投稿・削除・返信・DM・follow/unfollow・publish_article・process_gatesは対象、本文、費用、重複防止を示してから実行します。

手順

1. 設定先を決める

Codexのconfig.tomlまたはClaude Codeの.mcp.jsonへ、既存設定を保って追加します。

2. 秘密値を分離

X_HARNESS_API_KEYを共有ファイルやGitへ残さない方法を選びます。

3. 一覧で接続確認

アカウント、ゲート、利用量のread-only操作を一回ずつ実行します。

4. 変更ルールを追加

外部変更ツールは必ずpreview・対象確認・実行後照合を行うようAGENTS.mdへ記載します。

完了条件

• MCPツール一覧が取得できる
• 正しいWorkerとXアカウントをread-onlyで確認
• APIキーが会話・Gitへ残らない
• 外部変更ツールの実行前ルールがある

注意: MCPの接続確認でテスト投稿をしません。一覧取得と利用量取得だけで接続は確認できます。

Academy教材: X Harnessを導入する / Lesson 17-5

公式ソース

• X Harness GitHub — 公式リポジトリ
• X Harness / README.md — 機能、構成、MCP、導入、コスト
• X Harness / apps/worker/src/index.ts — route登録とCron処理
• X Harness / packages/db/schema.sql — D1のデータ構造
• X Harness / packages/mcp/src/index.ts — MCPツールとAPIの対応
• X Harness / packages/create-x-harness/src/steps/prompt.ts — X Developer申請、権限、認証情報の入力順
• X Harness / packages/x-sdk/src/oauth1.ts — OAuth 1.0a署名処理
• X Harness / packages/x-sdk/src/client.ts — X API操作と認証方式
• X Harness / packages/create-x-harness/src/commands/setup.ts — 再開可能なセットアップ全工程
• X Harness / packages/create-x-harness/src/steps/database.ts — D1作成とmigration
• X Harness / packages/create-x-harness/src/steps/deploy-worker.ts — Workerデプロイ
• X Harness / packages/create-x-harness/src/steps/deploy-admin.ts — Pages管理画面デプロイ
• X Harness / packages/create-x-harness/src/steps/secrets.ts — Worker Secrets登録
• X Harness / apps/web/src/components/auth-guard.tsx — APIキー認証
• X Harness / apps/web/src/hooks/use-selected-account.ts — 選択アカウントの保持
• X Harness / apps/worker/src/routes/health.ts — health endpoint
• X Harness / apps/worker/src/routes/capabilities.ts — 利用可能機能の判定
• X Harness / apps/web/src/app/settings/page.tsx — 自動機能とLINE接続設定
• X Harness / packages/mcp/src/tools/posts.ts — 投稿系ツール
• X Harness / packages/mcp/src/tools/gates.ts — ゲート系ツール
• X Harness / packages/create-x-harness/src/steps/mcp-config.ts — Claude Code用設定生成
• X Harness / packages/create-x-harness/src/steps/scraper-setup.ts — Codex設定例とスキル導入

関連ガイド

• Harnessシリーズ公式ガイド索引
• X自動化ツール比較
• L Harness公式ガイド