🔧 x-harness

Open-source X (Twitter) API toolkit powered by Cloudflare Workers

X API 従量課金制対応のサーバーレス SNS 自動化ツール — 5分でデプロイ。

Getting Started · Features · MCP (Claude / Antigravity) · API Reference

✨ Features

🏗️ Architecture

┌─────────────────────────────────────────────────────┐
│         Cloudflare Workers (無料枠)                   │
│  https://x-harness.YOUR_SUB.workers.dev              │
│                                                       │
│  ┌─────────┐  ┌──────────┐  ┌──────────┐  ┌──────┐  │
│  │ OAuth   │  │ X API    │  │ Cron     │  │ D1   │  │
│  │ PKCE    │  │ Proxy    │  │ Triggers │  │ (DB) │  │
│  └─────────┘  └──────────┘  └──────────┘  └──────┘  │
│         ↑ HARNESS_API_KEY (Bearer Token)              │
└─────────┼─────────────────────────────────────────────┘
          │ HTTPS
┌─────────▼──────────────────────────────────────┐
│  ローカル環境                                    │
│                                                  │
│  ┌──────────────┐  ┌───────────┐  ┌──────────┐  │
│  │ MCP Server   │  │ Local     │  │ CLI      │  │
│  │ (Claude Code │  │ Sync Dir  │  │ (curl)   │  │
│  │  Antigravity │  │ ┌tweets/  │  │          │  │
│  │  VS Code)    │  │ ├analytics│  │          │  │
│  │  21 tools    │  │ └rules/   │  │          │  │
│  └──────────────┘  └───────────┘  └──────────┘  │
└──────────────────────────────────────────────────┘

セキュリティ: X API トークンは Workers の D1 に保存されローカルには降りてきません。 ローカルからは HARNESS_API_KEY で Worker に接続し、Worker が内部でトークンを自動解決します。 API キー認証は timing-safe comparison でタイミング攻撃を防止しています。

🚀 Getting Started

Prerequisites

• Node.js v18+
• Wrangler CLI v4+
• X Developer Account (Pay-per-use クレジット制)
• Cloudflare アカウント (無料枠で OK)

Step 1. Clone & Install

git clone https://github.com/cheesebergling/x-harness.git
cd x-harness
npm install

Step 2. 環境変数設定

# テンプレートをコピー
cp .dev.vars.example .dev.vars

# .dev.vars を編集して各値を設定
# 安全な API キー生成:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Step 3. Cloudflare リソース作成

# Cloudflare にログイン
wrangler login

# D1 データベース作成
wrangler d1 create x-harness-db
# → 出力される database_id を wrangler.toml に設定

# マイグレーション実行（リモート）
wrangler d1 migrations apply x-harness-db --remote

Step 4. X Developer Portal 設定

1. developer.x.com でアプリ作成
2. User authentication settings → OAuth 2.0 を有効化
3. Type of App → Web App
4. Callback URI → https://x-harness.YOUR_SUB.workers.dev/api/auth/callback
5. 全スコープ有効化: tweet.read/write, users.read, dm.read/write, like.read/write, follows.read/write, bookmark.read/write, offline.access

Step 5. シークレット設定 & デプロイ

# シークレットを設定
wrangler secret put HARNESS_API_KEY       # 任意の安全な文字列
wrangler secret put X_CLIENT_ID           # X Developer Portal から
wrangler secret put X_CLIENT_SECRET       # X Developer Portal から
wrangler secret put X_CALLBACK_URL        # https://x-harness.YOUR_SUB.workers.dev/api/auth/callback

# デプロイ
npm run deploy

Step 6. OAuth 認証（1回だけ）

# 認証URLを取得
curl -H "Authorization: Bearer YOUR_HARNESS_API_KEY" \
  https://x-harness.YOUR_SUB.workers.dev/api/auth/authorize

# → 返されたURLをブラウザで開いて X アカウントを認可
# → callback で自動的にトークンが D1 に保存される

Step 7. 動作確認

# 認証状態を確認
curl -H "Authorization: Bearer YOUR_HARNESS_API_KEY" \
  https://x-harness.YOUR_SUB.workers.dev/api/auth/status

🤖 MCP Server

Claude Code / Antigravity / VS Code から x-harness を直接操作できます。

セットアップ

cd mcp
npm install
npm run build

Claude Code に登録

claude mcp add x-harness --type stdio \
  -e X_HARNESS_URL=https://x-harness.YOUR_SUB.workers.dev \
  -e X_HARNESS_API_KEY=YOUR_HARNESS_API_KEY \
  -e X_HARNESS_SYNC_DIR=/path/to/your/sync/dir \
  -- node ./mcp/dist/index.js

Antigravity / VS Code MCP 設定

settings.json に追加:

{
  "mcpServers": {
    "x-harness": {
      "command": "node",
      "args": ["./mcp/dist/index.js"],
      "env": {
        "X_HARNESS_URL": "https://x-harness.YOUR_SUB.workers.dev",
        "X_HARNESS_API_KEY": "YOUR_HARNESS_API_KEY",
        "X_HARNESS_SYNC_DIR": "C:\\Users\\YOU\\x-harness-data"
      }
    }
  }
}

Note: args のパスはリポジトリのクローン先に合わせて絶対パスに変更してください。 例: ["C:\\path\\to\\x-harness\\mcp\\dist\\index.js"]

利用可能なツール (21種)

📝 Tweet (5)

📊 Analytics (3)

📩 DM (3)

✍️ Writing Rules (5)

🔄 Local Sync (3)

🔐 Auth & Usage (3)

🔄 Local Sync

Syncthing のように、Worker上の投稿・分析データをローカルフォルダに自動同期します。

フォルダ構造

<sync_dir>/
  ├── tweets/                # ツイートログ
  │   ├── 2026-03.json       # 月別アーカイブ
  │   └── latest.json        # 直近データ
  ├── analytics/
  │   ├── followers.json     # フォロワー推移
  │   ├── engagement.json    # エンゲージメント集計
  │   └── usage.json         # API使用量
  ├── writing-rules/
  │   ├── rules.json         # 全ルール (JSON)
  │   └── X投稿_標準.md      # 各ルールの Markdown
  └── sync-config.json       # 同期設定

MCP から使う

# 1. 同期先を設定
configure_sync(sync_dir="/path/to/data", auto_sync_minutes=30)

# 2. 即時同期
sync_now()

# 3. 状態確認（30分経過していれば自動同期も実行）
get_sync_status()

✍️ Writing Rules

X 投稿のライティングスタイルを定義・保存・管理できます。

{
  "name": "X投稿・カジュアル",
  "tone": "casual",
  "persona": "30代マーケター目線。フォロワーとの距離感を大切に。",
  "constraints": {
    "max_chars": 280,
    "forbidden_words": ["PR", "案件"],
    "hashtag_rules": { "max": 3, "position": "end" },
    "emoji_usage": "moderate"
  },
  "templates": [
    "【{{topic}}】\n{{body}}\n\n{{cta}}",
    "{{hook}}\n\n→ {{body}}\n\n#{{tag1}} #{{tag2}}"
  ],
  "examples": {
    "good": ["短い文で要点を伝え、最後にCTAを入れる"],
    "bad": ["長すぎる文章、ハッシュタグの乱用"]
  }
}

📡 API Reference

全エンドポイントは Authorization: Bearer <HARNESS_API_KEY> が必要です。

Authentication

Tweets

Analytics

Writing Rules

Sync

Direct Messages

Usage & Cost

🛡️ Security

💰 API 料金試算 (Pay-per-use)

24時間UTCデデュプリケーション: 同一リソースへの重複リクエストは1回分の課金

🛠️ Tech Stack

• Runtime: Cloudflare Workers (Hono v4)
• Database: Cloudflare D1 (SQLite)
• Storage: Cloudflare R2 (Media)
• Cron: Cron Triggers (5分毎)
• MCP: @modelcontextprotocol/sdk (Claude Code / Antigravity)
• Language: TypeScript

📄 License

This project is licensed under the MIT License.

Built with ❤️ by the x-harness community

⭐ Star on GitHub · 🐛 Report Bug · 💡 Request Feature