Threads MCPサーバー

threads-mcpは、公式Threads API用のstdio MCPサーバーです。Meta Threadsの公開ドキュメントに準拠しつつ、認証、投稿、読み取り、モデレーション、インサイト、検索、位置情報、セットアップ診断のための実用的なMCPツールを提供します。

現在のビルドは、公式に文書化されたThreadsの機能と公式Postmanコレクションに限定されています。公開パッケージとして維持が困難な、文書化されていないフォールバックエンドポイントや便利なラッパーには依存していません。

ハイライト

• 公式Threads APIスコープのみに対応

• 認証、プロフィール検索、投稿、読み取り、返信、インサイト、検索、位置情報、oEmbed、診断用のMCPツール

• 投稿入力はcamelCaseでモデル化され、内部でThreadsが期待するsnake_caseパラメータにシリアライズされます

• マルチステップのカルーセル投稿をサポート

• リトライ、ポーリング、ページネーション、正規化されたMeta APIエラーを処理する共有クライアント層

Related MCP server: threads-mcp

クイックスタート

1. 依存関係をインストールします:

npm install

2. サーバーをビルドします:

npm run build

3. ローカル環境ファイルを作成し、少なくともTHREADS_ACCESS_TOKENを設定します。

4. トークンがまだ必要な場合は、ローカルのOAuthヘルパーを実行します:

npm run auth:token

5. サーバーを起動します:

node dist/index.js

6. 実際のカウントに対して投稿やモデレーションフローを使用する前に、validate_setupを呼び出してください。

ツールカタログ

認証

• exchange_code_for_token

• get_long_lived_access_token

• refresh_access_token

• get_app_access_token

プロフィールと検索

• get_me

• get_profile

• get_profile_threads

投稿とライフサイクル

• get_publishing_limit

• create_thread_container

• publish_thread

• create_and_publish_thread

• repost_thread

• delete_thread

読み取りと返信

• get_threads

• get_thread

• get_replies

• get_thread_conversation

• get_pending_replies

• manage_reply

• manage_pending_reply

インサイト、検索、埋め込み

• get_user_insights

• get_thread_insights

• search_threads

• get_mentions

• get_oembed

位置情報と診断

• search_locations

• get_location

• validate_setup

v1の対象外

• Webhook

• 埋め込みOAuthコールバックホスティング

• 公式ドキュメントや公式Postmanコレクションでカバーされていない、文書化されていないフォールバックエンドポイントや便利な機能

アーキテクチャ

サーバーはいくつかの明確な層に分かれています:

• src/index.ts: MCP stdioトランスポートをブートストラップします。

• src/threads/client.ts: 認証されたHTTP呼び出し、リトライ、ページネーション、ポーリング、正規化されたMeta APIエラーを管理します。

• src/tools/: ツールファミリーごとに1つのモジュールと共有スキーマが含まれています。

投稿入力モデルは、text、image、video、carousel、replyをカバーする単一の公開判別共用体として公開されています。

前提条件

サーバーがライブAPI呼び出しを行うには、以下のすべてが必要です:

• Threadsユースケース用に構成されたMetaアプリ

• 操作対象のアカウントのThreadsユーザーアクセストークン

• 統合に必要な高度なアクセス権とアプリ審査

• サーバーを実行するマシン上のNode.js 20以上

環境変数

ユーザートークンツールに必須:

• THREADS_ACCESS_TOKEN

オプション:

• THREADS_APP_ID

• THREADS_APP_SECRET

• THREADS_REDIRECT_URI

• THREADS_API_BASE_URL

• THREADS_USER_ID

• THREADS_MAX_RETRIES

• THREADS_RETRY_BASE_DELAY_MS

• THREADS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_POLL_INTERVAL_MS

.env.exampleをコピーし、少なくともアクセストークンを設定してください。THREADS_APP_IDとTHREADS_APP_SECRETは、認証ヘルパーツールや、明示的なアプリアクセストークンを渡さない場合のget_oembedにも必要です。

THREADS_APP_IDの取得方法

• Meta for Developersダッシュボードでアプリを開きます: https://developers.facebook.com/apps/

• Threadsユースケースで作成されたアプリを開きます

• Use Cases -> Threads -> Customize -> Settingsに移動します

• そのページからThreads App IDをコピーします

• その値をTHREADS_APP_IDとして使用します

重要:

• トップレベルのアプリダッシュボードや設定ページにある一般的なMetaアプリIDは使用しないでください

• Use Cases -> Threads -> Customize -> SettingsにあるThreadsユースケース固有の認証情報を使用してください

THREADS_APP_SECRETは同じThreadsユースケース設定ページから取得できます。非公開にしてください。

トークンヘルパースクリプト

リポジトリには、Meta Threadsアクセストークンフローに従うローカルOAuthヘルパーが含まれています:

1. Threads認証ウィンドウを開く

2. ローカルコールバックURLで認証コードを受け取る

3. 短期トークンと交換する

4. 長期トークンと交換する

5. 結果を.envにTHREADS_ACCESS_TOKENとして保存する

セットアップ:

• Metaアプリの認証情報を.envに追加します

• アプリの有効なOAuthリダイレクトURIがTHREADS_REDIRECT_URIと一致していることを確認します

実行:

npm run auth:token

オプションフラグ:

• --redirect-uri http://127.0.0.1:8788/callback

• --env-file .env.local

• --no-open

ツールファミリーごとの必須スコープ

• threads_basic get_me、get_profile、get_threads、get_thread、およびベースラインセットアップ検証で使用されます。

• threads_content_publish get_publishing_limit、create_thread_container、publish_thread、create_and_publish_threadで使用されます。

• threads_read_replies get_repliesおよびvalidate_setup内の安全な返信読み取りプローブで使用されます。

• threads_manage_replies manage_replyで使用されます。

• threads_manage_insights get_user_insightsおよびget_thread_insightsで使用されます。

• threads_keyword_search search_threadsで使用されます。

• threads_profile_discovery 公開アカウント検索シナリオのget_profileおよびget_profile_threadsで使用されます。

• threads_location_tagging search_locations、get_location、およびlocationIdを設定する投稿フローで使用されます。

• threads_delete delete_threadで使用されます。

validate_setupは、threads_basic、threads_content_publish、threads_read_replies、threads_manage_insights、threads_keyword_search、threads_profile_discovery、threads_location_taggingのアクセス権を推論するために安全なプローブを実行します。意図的にthreads_manage_repliesやthreads_deleteに対する破壊的なプローブは実行しないため、これらのスコープはセットアップによって積極的に検証されません。

投稿の動作

サーバーは公式のコンテナオプションをcamelCaseでモデル化し、内部でThreads APIが期待するsnake_caseパラメータにシリアライズします。

サポートされている入力:

• 共通フィールド: text、replyControl、replyToId、quotePostId、topicTag、locationId、textEntities、allowlistedCountryCodes

• テキスト専用フィールド: linkAttachment、pollAttachment、textAttachment、gifAttachment、enableReplyApprovals、autoPublishText、isGhostPost

• 画像または動画フィールド: imageUrl、videoUrl、altText、isSpoilerMedia

• カルーセルアイテム: アイテムごとのメディアフィールドを持つ画像または動画アイテムの検証済み配列

カルーセル投稿は、公式のマルチステップフローに従います:

1. is_carousel_item=trueを指定して、画像または動画ごとに1つのアイテムコンテナを作成する

2. children=[...]を指定して親カルーセルコンテナを作成する

3. 親コンテナを公開する

カバレッジに関する注記

リポジトリは現在、以下の公式Threads APIファミリーをカバーしています:

• 認証ヘルパー

• 投稿（引用投稿、再投稿、コンテナステータスポーリングを含む）

• ユーザープロフィール検索および公開プロフィール投稿の取得

• Threadsメディアの取得

• 返信の取得、フラット化された会話、保留中の返信、非表示/表示、承認/無視フロー

• ユーザーおよび投稿のインサイト

• キーワード検索およびメンション

• 位置情報の検索および取得

• oEmbed

• セットアップ診断

ローカルMCP設定例

Claude Desktopスタイルの設定例:

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/absolute/path/to/threads-mcp/dist/index.js"],
      "env": {
        "THREADS_ACCESS_TOKEN": "thdt_your_user_access_token",
        "THREADS_APP_ID": "optional_app_id",
        "THREADS_APP_SECRET": "optional_app_secret"
      }
    }
  }
}

このパッケージをCLIとして公開する場合、commandはthreads-mcpになります。

公開

パッケージメタデータは、公開パッケージとしてnpm公開用に構成されています:

• パッケージ名: threads-mcp

• 現在のバージョン: 0.0.0

• CLIエントリーポイント: threads-mcp

• 公開アクセス: public

公開前に以下を実行してください:

npm run build
npm test
npm publish --access public

prepublishOnlyは、npm publish中にビルドおよびテストステップを自動的に実行するように構成されています。

開発

Node.jsが利用可能な状態で依存関係をインストールします:

npm install
npm run build
npm test

推奨される手動チェック:

1. npm run buildを実行してTypeScriptコンパイルを確認します。

2. npm testを実行してスキーマ、クライアント、ツール登録テストを実行します。

3. node dist/index.jsでサーバーを起動します。

4. 最初に実際のトークンを使用してvalidate_setupを呼び出します。

5. テスト用のThreadsアカウントに対してcreate_thread_containerとpublish_threadを試します。

既知の制限

• v1ではトランスポートはstdioのみです

• 埋め込みOAuthコールバックサーバーはありません。トークン交換ヘルパーは代わりにMCPツールとして公開されています

• validate_setupは、状態を変更するモデレーション呼び出しを行わずにthreads_manage_repliesを安全に検証できません

• validate_setupは、状態を変更する削除プローブも実行しません

• create_and_publish_threadは、autoPublishText=trueを意図的に拒否します。このフラグはツールの明示的な2ステップ契約と競合するためです

• 返信投稿は、公式のreply_to_idパラメータによってサポートされる専用のreplyバリアントとしてモデル化されており、現在は公開スキーマでのテキスト返信を対象としています

• ライブAPI動作の検証は、有効なアプリ認証情報、承認されたスコープ、および実際のThreadsアカウントに依存します

APIスコープおよびエンドポイント選択に使用したソース

• Meta Threads APIリファレンス: https://developers.facebook.com/docs/threads/reference

• Meta Threads投稿リファレンス: https://developers.facebook.com/docs/threads/reference/publishing

• Meta公式Postmanワークスペース: https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api