threads-mcp

Threads API 用の MCP サーバーです。プラットフォーム I/O のみを行い、それ以外は行いません。投稿の公開、自分の投稿の取得、インサイトの取得、公開クォータの確認。編集ロジックも、スケジューリングも、何を書くべきかについての意見もありません。

これは、エージェントが Threads に 到達する ために必要な部品です。何を投稿するかはあなたの問題です。

npx -y @andreaselmi/threads-mcp    # needs THREADS_ACCESS_TOKEN in the environment

• クイックスタート

• ツール

• アクセストークンを取得する

• クライアントへの組み込み

• トラブルシューティング

• 意図的に行わないこと

• 開発

クイックスタート

Node 20 以上 が必要です。インストールは不要です。MCP クライアントは npx でサーバーを実行し、初回使用時に取得します。

1. 長期アクセストークンを取得します — 詳細な手順は後述。これだけが本当に面倒な部分ですが、これは Meta 側の問題であり、このパッケージのせいではありません。

2. MCP クライアントを起動するシェルで、それをエクスポートします:

   export THREADS_ACCESS_TOKEN="THQ..."

3. サーバーをクライアントの MCP 設定に追加します:

   {
     "mcpServers": {
       "threads": {
         "command": "npx",
         "args": ["-y", "@andreaselmi/threads-mcp"]
       }
     }
   }

4. クライアントを再起動し、自分が誰かを尋ねてください。threads_whoami を呼び出し、あなたのユーザー名で答えるはずです。

クライアントを関与させる前にサーバーが動作することを確認するには:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y @andreaselmi/threads-mcp

threads-mcp という名前を含む JSON 行が表示されれば、起動してトークンを読み取ったことを意味します。stderr のエラーメッセージが何が不足しているかを示します。

Related MCP server: meta-threads-mcp

ツール

2つの公開ツールは destructiveHint: true とマークされ、それ以外は readOnlyHint です。破壊的なツールの前に確認を求めるクライアントは、これらの前にも確認を求めますが、それで正しいのです。公開された投稿は即座に公開され、API では編集も削除もできません。 削除するには Threads アプリを開く必要があります。

threads_post_insights は 自分の 投稿のみのインサイトを読み取り、threads_manage_insights スコープが必要です。threads_publishing_limit は直近24時間のクォータを報告します。デフォルトではアカウントあたり250件です。

threads_publish_container が存在する理由

Threads での公開は2回の呼び出しで構成されます。コンテナを作成し、それを公開します。2番目の呼び出しが失敗した場合、コンテナは存在したままで、24時間有効です。操作全体を再試行すると同じテキストが2回投稿されてしまいます。公開が失敗した場合、このサーバーはエラーメッセージにコンテナ ID を含めます。それを threads_publish_container に渡せば、ジョブをちょうど1回だけ完了できます。

また、サーバーはコンテナが FINISHED に達するまで待ってから公開します。2秒ごとに最大1分間ポーリングするため、遅いコンテナが失敗と誤判定されることはありません。

アクセストークンを取得する

Meta のフローには4つのステップがあり、近道はありません。初回は15分を見込んでください。

1. アプリを作成する

developers.facebook.com/apps にアクセスし、Threads ユースケースでアプリを作成します。ダッシュボードは2組の認証情報を生成しますが、Threads 用の アプリ ID とシークレットを使用してください。Facebook 用のものではありません。ここでほとんど全員がつまずきます。

2. スコープとテスターを追加する

Threads ユースケースで、必要なスコープを追加します:

次に、自分の Threads アカウントをテスターとして追加し、そのアカウントの設定から招待を承認 します（アカウント → Webサイトの権限 → 招待）。招待が承認されるまで、すべての呼び出しは招待に言及しない権限エラーで失敗します。

3. 短期トークンを取得する

ブラウザで認証ウィンドウを開き、プレースホルダーを置き換えます:

https://threads.net/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code

承認すると、?code=... が付いた redirect_uri にリダイレクトされます。リダイレクト URI はアプ設定に登録されたものと完全に一致している必要があります。コードをコピーして（使い捨てで、数分で期限切れになります）、交換してください:

curl -X POST https://graph.threads.net/oauth/access_token \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=THE_CODE_FROM_THE_REDIRECT

これで短期トークンが返されます。有効期間は 1時間 です。ここで止めないでください。

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

curl -G https://graph.threads.net/access_token \
  -d grant_type=th_exchange_token \
  -d client_secret=YOUR_APP_SECRET \
  -d access_token=THE_SHORT_LIVED_TOKEN

結果の有効期間は 60日間 です。これが THREADS_ACCESS_TOKEN の値です。

有効期間を維持する

長期トークンは、取得から24時間以上経過し、期限が切れる前に更新できます。更新のたびにさらに60日間延長されます:

curl -G https://graph.threads.net/refresh_access_token \
  -d grant_type=th_refresh_token \
  -d access_token=YOUR_LONG_LIVED_TOKEN

60日間使用されなかったトークンは期限切れとなり、更新できません。ステップ3からやり直すことになります。カレンダーにリマインダーを入れておいてください。警告は何も来ません。

クライアントへの組み込み

環境変数

トークンは起動時に環境変数から読み取られ、どこにも書き込まれません。ファイルにも、ログ行にも書き込まれません。設定ファイルに書き込むよりも、シェルでエクスポートすることをお勧めします。設定ファイルはコミットされてしまいますが、シェルのエクスポートはコミットされません。

Claude Code

claude mcp add threads --scope user -- npx -y @andreaselmi/threads-mcp

または、プロジェクトのルートに .mcp.json をコミットすると、そのプロジェクトで作業する全員がサーバーを利用できます:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp@^0.1.0"]
    }
  }
}

^0.1.0 の固定は修正を取り込みますが、ツールを変更する将来のメジャーバージョンは取り込みません。/mcp で接続を確認してください。

Claude Desktop、Cursor、その他のクライアント

同じ構成を、各クライアントの設定ファイルに記述します。Claude Desktop では claude_desktop_config.json、Cursor では ~/.cursor/mcp.json です。シェル環境を 継承しない クライアントでは、トークンを明示的に渡す必要があります:

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"],
      "env": { "THREADS_ACCESS_TOKEN": "THQ..." }
    }
  }
}

この方法を使う場合、そのファイルには生きた資格情報が含まれることになります。バージョン管理の対象外にしてください。

代わりにインストールする

毎回 npx を使いたくない場合は:

npm install -g @andreaselmi/threads-mcp

その場合は、args なしで "command": "threads-mcp" を使用します。

トラブルシューティング

サーバーが起動しない / クライアントに CONNECTION_CLOSED と表示される。 プロセスが起動時に終了しています。ほとんどの場合、クライアントを起動した環境に THREADS_ACCESS_TOKEN が設定されていないためです。ターミナルでエクスポートしても、すでに実行中のアプリや Dock から起動したアプリには届きません。実際のメッセージを確認するには、サーバーを手動で実行してください:

npx -y @andreaselmi/threads-mcp

理由を出力して終了します。

Invalid OAuth access token またはそれに類似するエラー。 トークンの期限が切れている（60日）か、ステップ3の短期トークンをまだ使用しています。ステップ4をやり直してください。

動作するはずの呼び出しで権限エラーが発生する。 スコープが不足している（インサイトと公開にはそれぞれ専用のスコープが必要）か、テスター招待が Threads アカウントの設定から承認されていないかのどちらかです。

Post is N characters, the Threads limit is 500。 これはリクエストを送信する前にこのサーバーが発生させるエラーなので、何も公開されていません。テキストを分割してください。

公開に失敗し、公開されたかどうか確信が持てない。 エラーを読んでください。コンテナ ID が含まれている場合、コンテナは存在し、投稿は 公開されていません。再公開する代わりに、その ID を threads_publish_container に渡してください。ID が含まれていない場合は、再試行する前に threads_list_posts を確認してください。

クォータを使い切った。 threads_publishing_limit は直近24時間のウィンドウを表示します。アカウントあたり250件です。クォータを使い切ると、ウィンドウから投稿が期限切れで外れるまで何も公開できません。

意図的に行わないこと

テキスト投稿のみです。画像、動画、カルーセル、リンク添付はありません。自分自身の投稿のみを読み取り、返信、メンション、他の人のコンテンツは読み取りません。スケジュールも、タイマーによる再試行も、呼び出し間の状態保持も行いません。データベースも持たず、何も記憶しません。

また、何を 投稿するかについても何も知りません。テーマも、トーンも、編集ルールもここにはありません。それらは呼び出し側に属します。プロダクト固有の動作を追加するプルリクエストは、呼び出し側に移すよう求められます。

開発

npm install
npm test          # vitest, no network: fetch is stubbed
npm run dev       # run the server from source over stdio
npm run build     # tsc to dist/

すべてのテストはフェイクの fetch に対して実行されるため、テストスイートが実際の API に触れることはなく、トークンも不要です。Issue とプルリクエスト: github.com/andreaselmi/threads-mcp。

ライセンス

MIT