Blacktwist

BlackTwist MCP サーバー

BlackTwist MCP（Model Context Protocol）サーバーを使うと、Claude、Cursor、その他の MCP 互換クライアントなどの AI アシスタントから BlackTwist アカウントを操作できます。投稿の作成、分析データの確認、下書きの管理などを行えます。

クイックスタート

BlackTwist MCP サーバーへの接続方法は、OAuth（claude.ai での使用に推奨）とAPI キー（デスクトップクライアントおよび CLI ツール向け）の 2 つです。

オプション A：OAuth で接続する（claude.ai）

claude.ai をカスタムコネクターとして使用する場合は、OAuth が最も簡単な方法です。API キーは必要ありません。

1. claude.ai > Settings > Integrations に移動します（またはカスタムコネクターを追加します）
2. MCP サーバーの URL を入力します：https://blacktwist.app/api/mcp
3. Claude が OAuth エンドポイントを自動的に検出して自身を登録し、BlackTwist アカウントでサインインするためのページに移動します
4. サインインすると接続が確立され、Claude から BlackTwist アカウントを使用できるようになります

OAuth トークンは自動的に更新されるため、アクセス権を取り消さない限り、再認証は必要ありません。

オプション B：API キーで接続する

Claude Desktop、Claude Code、Cursor、その他 OAuth をサポートしない MCP クライアントでは、API キーを使用します。

1. API キーを生成する

1. BlackTwist を開き、Settings（歯車アイコン）に移動します
2. サイドバーの MCP タブをクリックします
3. Create API Key をクリックし、名前（例：「Claude Desktop」）を付けて、Create Key をクリックします
4. キーをすぐにコピーします。再表示はできません

2. MCP クライアントを設定する

以下を MCP クライアントの設定に追加します。

Claude Desktop（claude_desktop_config.json）：

{
  "blacktwist": {
    "command": "npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://blacktwist.app/api/mcp",
      "--header",
      "Authorization:${BLACKTWIST_TOKEN}"
    ],
    "env": {
      "BLACKTWIST_TOKEN": "Bearer YOUR_API_KEY"
    }
  }
}

node.js v22 が必要です。nvm を使用している場合は、正しいバージョンを使ってください。

{
  "blacktwist": {
    "command": "/Users/<your_user>/.nvm/versions/node/v22.22.0/bin/npx",
    "args": [
      "-y",
      "mcp-remote@latest",
      "https://blacktwist.app/api/mcp",
      "--header",
      "Authorization:${BLACKTWIST_TOKEN}"
    ],
    "env": {
      "BLACKTWIST_TOKEN": "Bearer YOUR_API_KEY",
      "PATH": "/Users/<your_user>/.nvm/versions/node/v22.22.0/bin:/usr/local/bin:/usr/bin:/bin",
      "NODE_PATH": "/Users/<your_user>/.nvm/versions/node/v22.22.0/lib/node_modules"
    }
  }
}

Claude Code

ターミナルで実行します。

claude mcp add --transport http blacktwist https://blacktwist.app/api/mcp --header "Authorization: Bearer YOUR_API_KEY"

または、プロジェクトのルートにあるファイル .mcp.json を編集します。

{
  "mcpServers": {
    "blacktwist": {
      "type": "url",
      "url": "https://blacktwist.app/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor（Settings > MCP）：

• 名前： blacktwist
• タイプ： url
• サーバー URL： https://blacktwist.app/api/mcp
• ヘッダー： Authorization: Bearer YOUR_API_KEY

3. 使用を開始する

接続すると、AI アシスタントに次のような依頼ができます。

• 「接続済みのソーシャルアカウントを一覧表示して」
• 「Threads に明日の午前 9 時に『新機能をリリースしました！』と投稿するよう予約して」
• 「最新の下書きを『より効果的な導入に更新したコピー』に編集して」
• 「プロダクトのローンチに関するスレッドに 2 つ目の投稿を追加して」
• 「過去 7 日間の分析データを表示して」
• 「最適な投稿時間はいつ？」
• 「今後予定されている投稿を一覧表示して」
• 「最新の下書きに growth と product launch のタグを付けて」

---

サーバーの詳細

プロパティ	値
URL	https://blacktwist.app/api/mcp
認証	OAuth 2.1（PKCE）または Bearer トークン（API キー）
トランスポート	ストリーム可能な HTTP（ステートレス）
プロトコル	HTTP POST 上の JSON-RPC による MCP

---

チームコンテキスト（teamId）

ほとんどのツールでは、特定のチームを対象に操作するための省略可能な teamId パラメーターを使用できます。

動作：

1. teamId がチーム ID の場合、ツールはそのチームのコンテキストで動作します（メンバーシップが検証されます）。
2. teamId が "personal" の場合、ツールは個人モードで動作します（ユーザー自身のデータのみを対象とし、チームは対象外です）。
3. teamId が省略された場合、ツールはユーザーの設定に基づき、現在アクティブなチームを使用します。アクティブなチームがない場合は、"personal" と同じ扱いになります。

teamId に対応するツール： list_providers、list_posts、list_drafts、create_post、get_thread、delete_thread、reschedule_thread、list_time_slots、list_tags、get_subscription、get_follow_up_templates、およびすべての分析ツール。

teamId に対応しないツール： list_teams（すべてのチームを一覧表示）、get_user_settings（個人設定）、list_viral_templates / list_viral_template_categories（アカウント全体のコンテンツライブラリ）、edit_post / edit_thread / get_thread_follow_up / set_thread_follow_up / get_thread_tags / set_thread_tags / set_thread_auto_repost（スレッドベースのアクセスにより、userCanAccessThread を通じてチーム認証が内部的に処理されます）。

サブスクリプションへのアクセス： 有料プランが必要な分析ツールでは、まずユーザー自身のサブスクリプションが確認されます。ユーザーがサブスクリプションを持っていない場合、システムはユーザーが所属するチームのオーナーが有効なプランを契約しているかどうかも確認します。これにより、チームメンバーはチームオーナーのサブスクリプションを通じて有料機能を利用できます。

---

利用可能なツール

プロバイダー

list_providers

接続されているすべてのソーシャルメディアアカウント（Threads と Bluesky）を一覧表示します。

パラメーター	型	必須	説明
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を指定します。チームを指定すると、そのチームにリンクされたプロバイダーのみが表示されます。

戻り値： id、provider、providerUserId、providerUsername、displayName、profilePicture を含むプロバイダーの配列。

注： ほかの多くのツールでは、このレスポンスの providerId（id フィールド）または providerUserId が必要です。

---

チーム

list_teams

ユーザーが所属するすべてのチームを、ユーザーのロールと現在アクティブなチームを含めて一覧表示します。ユーザーの個人アカウント（チームに所属しないアカウント）を表す "personal" エントリが常に含まれます。

パラメーター： なし

戻り値： id、name、role（OWNER、ADMIN、MEMBER、GUEST）、isActive、createdAt を含むチームの配列。

個人アカウントのエントリの id は "personal" です。現在チームが選択されていない場合、isActive: true としてマークされます。

注： チームの id は、ほかのツール（list_posts、list_drafts、create_post など）に teamId として渡すことができます。個人アカウントを明示的に使用するには "personal" を指定します。teamId を省略すると、これらのツールはユーザーの現在アクティブなチームを自動的に使用します。

---

投稿とスレッド

create_post

新しい投稿またはスレッドを作成します。スレッドとは、複数の投稿をつなげたものです。

パラメーター	型	必須	説明
providerId	string	はい	list_providers のプロバイダー ID
posts	array	はい	投稿オブジェクトの配列（下記参照）
scheduleAt	string	いいえ	ISO 8601 の日時。省略すると下書きとして保存されます。タイムゾーンオフセットのない時刻（例：2025-03-15T09:00:00）は、ユーザーが設定したタイムゾーンで解釈されます。
autoRepost	object	いいえ	{ enabled: boolean, delays: string[] }。delays は時間単位で、例：7 日後と 14 日後の場合は ["168", "336"] です。省略すると、ユーザーのデフォルトの自動再投稿設定が適用されます。
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントの場合は "personal" を指定します。

自動的に適用されるデフォルトの動作：

• 自動再投稿： autoRepost が指定されておらず、ユーザーが設定で自動再投稿を有効にしている場合、デフォルトの間隔が最初の投稿に適用されます。これは下書きにも適用されるため、下書きにも予約時に適用される間隔が保持されます。reschedule_thread は scheduledAt のみを変更し、これらの間隔を遡って追加することはありません。
• フォローアップ（自動プラグ）： プロバイダーでデフォルトのフォローアップテンプレートが有効になっている場合、自動的にコピーされ、スレッドに添付されます。この処理が行われると、レスポンスに autoPlugApplied: true が含まれます。
• タイムゾーン： オフセットのない時刻は、ユーザーの notificationsTimezone 設定で解釈されます。オフセット（Z、+02:00、+0200）がある時刻は、タイムゾーンの参照なしで、その時点の時刻として使用されます。これは reschedule_thread と list_posts にも適用されます。

各投稿オブジェクト：

フィールド	型	必須	説明
text	string	はい	投稿の内容
topic	string	いいえ	トピックタグ
media	object[]	いいえ	公開 URL によるメディア添付ファイル（メディア添付ファイルを参照）
spoilerRanges	object[]	いいえ	テキストのネタバレ範囲（ネタバレを参照）
isSpoilerMedia	boolean	いいえ	true の場合、この投稿内のすべてのメディアにネタバレのマークが付けられます（ネタバレを参照）

例 — 単一の投稿：

{
  "providerId": "clx...",
  "posts": [{ "text": "Hello world!" }],
  "scheduleAt": "2025-03-15T09:00:00"
}

例 — スレッド：

{
  "providerId": "clx...",
  "posts": [
    { "text": "Thread time! Here's what I learned this week 🧵" },
    { "text": "1/ First lesson: consistency beats perfection" },
    { "text": "2/ Second lesson: engage with your community daily" }
  ],
  "scheduleAt": "2025-03-15T09:00:00"
}

メディア添付ファイル

media を受け付けるツール（create_post、edit_post、edit_thread、set_thread_follow_up）では、公開 URL を使って画像や動画を添付できます。サーバーがダウンロードし、Threads の仕様に照らして検証したうえで、自動的にアップロードします。

各メディアオブジェクト：

フィールド	型	必須	説明
url	string	はい	画像または動画の公開 URL
altText	string	いいえ	アクセシビリティ用の代替テキスト

Threads の画像仕様：

• 形式：JPEG、PNG
• 最大ファイルサイズ：8 MB
• 最大アスペクト比：10:1

Threads の動画仕様：

• 形式：MP4、MOV
• 最大ファイルサイズ：1 GB
• 長さ：最大 5 分
• 最大幅：1920px

例 — 画像付きの投稿：

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "Check out this view!",
      "media": [
        {
          "url": "https://example.com/photo.jpg",
          "altText": "Sunset over the mountains"
        }
      ]
    }
  ],
  "scheduleAt": "2025-03-15T09:00:00"
}

ネタバレ（Threads のみ）

ネタバレ機能を使うと、Threads でテキストやメディアの一部をぼかし効果で隠せます。閲覧者はタップすると、隠された内容を表示できます。

テキストのネタバレは、文字範囲の配列として定義します：

フィールド	型	必須	説明
offset	number	はい	文字位置（0 始まり）
length	number	はい	範囲内の文字数

• 投稿ごとのネタバレ範囲は最大 10 個です
• 範囲は text フィールド内の文字位置を参照します

メディアのネタバレは、投稿ごとに設定する単一の真偽値フラグです。isSpoilerMedia が true の場合、投稿内のすべてのメディア（画像と動画）は、閲覧者がタップして表示するまでぼかされます。

テキストとメディアのネタバレは独立しています。投稿には、両方、いずれか一方、またはどちらも設定できます。

例 — テキストのネタバレを含む投稿：

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "The winner is John!",
      "spoilerRanges": [{ "offset": 14, "length": 5 }]
    }
  ]
}

例 — メディアのネタバレを含む投稿：

{
  "providerId": "clx...",
  "posts": [
    {
      "text": "Spoiler alert! Check the image",
      "media": [{ "url": "https://example.com/reveal.jpg" }],
      "isSpoilerMedia": true
    }
  ]
}

レスポンス内（list_posts、list_drafts、get_thread）では、各投稿に以下が含まれます：

• spoilerRanges：{ offset, length } の配列（テキストのネタバレがない場合は空）
• isSpoilerMedia：真偽値（メディアがネタバレ設定されている場合は true）

---

list_posts

指定した日付範囲内の予約済みおよび公開済みの投稿を一覧表示します。

パラメーター	型	必須	説明
from	string	はい	開始日時（ISO 8601）。タイムゾーンオフセットのない時刻は、ユーザーに設定されたタイムゾーンで解釈されます。
to	string	はい	終了日時（ISO 8601）。タイムゾーンオフセットのない時刻は、ユーザーに設定されたタイムゾーンで解釈されます。
providerId	string	いいえ	プロバイダー ID（list_providers から取得）。指定した場合、このプロバイダーの投稿のみを返します。
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

list_drafts

すべての下書き投稿（まだ予約されていないもの）を一覧表示します。

パラメーター	型	必須	説明
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

get_thread

指定したスレッドと、そのすべての投稿、メディア、分析情報を取得します。

パラメーター	型	必須	説明
threadId	string	はい	スレッド ID
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

edit_post

単一の投稿のテキストコンテンツ、トピック、またはメディアを編集します。編集できるのはステータスが READY（下書きまたは予約済み）の投稿のみです。公開済み、処理中、または失敗した投稿は拒否されます。まず get_thread を使用して投稿 ID を取得してください。

パラメーター	型	必須	説明
postId	string	はい	投稿 ID（get_thread で取得）
content	string	いいえ	新しいテキストコンテンツ
topic	string	いいえ	新しいトピックタグ。トピックを削除するには null を渡します。
media	object[]	いいえ	公開 URL を使用してすべてのメディアを置き換えます（メディア添付を参照）。省略すると、既存のメディアは変更されません。
spoilerRanges	object[]	いいえ	テキストのネタバレ範囲を置き換えます（ネタバレ（スレッドのみ）を参照）。省略すると変更されません。すべて削除するには [] を渡します。
isSpoilerMedia	boolean	いいえ	メディアのネタバレフラグを設定します。true = ぼかし、false = ネタバレ設定を解除します。省略すると変更されません。

content、topic、media、spoilerRanges、isSpoilerMedia のいずれかを指定する必要があります。

戻り値： postId、threadId、updated（変更されたフィールドを示すオブジェクト）。

例 — テキストを更新：

{
  "postId": "clx...",
  "content": "Updated post content"
}

例 — テキストを更新してトピックをクリア：

{
  "postId": "clx...",
  "content": "New content",
  "topic": null
}

edit_thread

投稿を追加、削除、または並べ替えてスレッドを編集します。希望する投稿の完全なリストを指定します。既存の投稿（id あり）は更新され、新しい投稿（id なし）は作成され、リストに含まれない既存の投稿は削除されます。すべての投稿のステータスが READY のスレッドのみ編集できます。

パラメーター	型	必須	説明
threadId	string	はい	スレッド ID
posts	array	はい	投稿の順序付き配列（最小 1 件）。順序によって postOrder（0 始まり）が決まります。以下を参照してください。

各投稿オブジェクト：

フィールド	型	必須	説明
id	string	いいえ	既存の投稿の投稿 ID。この位置に新しい投稿を作成する場合は省略します。
text	string	はい	投稿内容
topic	string	いいえ	トピックタグ
media	object[]	いいえ	公開 URL を使用したメディア添付（メディア添付を参照）
spoilerRanges	object[]	いいえ	テキストのネタバレ範囲（ネタバレ（スレッドのみ）を参照）
isSpoilerMedia	boolean	いいえ	true の場合、この投稿のすべてのメディアにネタバレ設定が適用されます

新しい投稿は、既存のスレッドから scheduledAt、provider、providerUserId、teamId を引き継ぎます。

戻り値： threadId、postsUpdated、postsCreated、postsDeleted、totalPosts。

例 — 並べ替えて投稿を追加：

{
  "threadId": "abc123",
  "posts": [
    { "id": "existing-post-2", "text": "Now this is first" },
    { "id": "existing-post-1", "text": "Now this is second" },
    { "text": "Brand new third post" }
  ]
}

例 — 投稿を削除（リストから省略）：

{
  "threadId": "abc123",
  "posts": [{ "id": "existing-post-1", "text": "Keep only this one" }]
}

delete_thread

スレッドとそのすべての投稿を完全に削除します。

Parameter	Type	Required	Description
threadId	string	Yes	スレッド ID
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントには "personal" を指定します。

reschedule_thread

スレッドの予約日時を変更します。

Parameter	Type	Required	Description
threadId	string	Yes	スレッド ID
scheduledAt	string	Yes	新しい日時（ISO 8601）。タイムゾーンオフセットのない時刻は、ユーザーに設定されたタイムゾーンで解釈されます。
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントには "personal" を指定します。

Note: これは scheduledAt のみを変更します。自動再投稿の遅延を追加したり、フォローアップのないスレッドにフォローアップを追加したりすることはありません。その場合は set_thread_auto_repost と set_thread_follow_up を使用してください。

set_thread_auto_repost

既存のスレッドの自動再投稿を設定または解除します。自動再投稿では、投稿後に各遅延時間が経過するたびに、スレッドの最初の投稿が再公開されます。

Parameter	Type	Required	Description
threadId	string	Yes	スレッド ID
enabled	boolean	Yes	自動再投稿を有効にするかどうか。false の場合、スレッドからすべての遅延が削除されます。
delays	string[]	No	時間単位の遅延を文字列で指定します。例：7日、14日、30日の場合は ["168", "336", "720"]。enabled が true の場合は必須です。既存の遅延を置き換えます。追加ではありません。

遅延は、正の整数で時間単位の値を指定する必要があります。delays 配列が空または未指定の状態で有効化すると、スレッドの設定が暗黙にクリアされるのではなく、リクエストが拒否されます。

Returns: threadId、enabled、delays。

ユーザーのデフォルトの遅延（autoRepostDelays）を確認するには get_user_settings を、スレッドの現在の autoRepostDelay を確認するには get_thread を使用します。新しい投稿にはデフォルトが自動的に適用されます。このツールは、投稿後にスレッドを変更するためのものです。

---

タグ

タグは投稿（下書き、予約済み、公開済み）の整理に使用でき、アプリの投稿分析ビューのフィルタリングにも利用できます。タグはワークスペースごとに管理されます。チームタグはチーム全体で共有され、個人タグは非公開です。タグはスレッド全体に適用され、スレッド内の個々の投稿には適用されません。

list_tags

投稿を整理するために、ワークスペースで利用できるタグを一覧表示します。

Parameter	Type	Required	Description
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントの場合は "personal" を渡します。

戻り値： { tags } — id、name、color を含むタグの配列です。

get_thread_tags

スレッドに現在設定されているタグを取得します。

Parameter	Type	Required	Description
threadId	string	Yes	タグを取得するスレッドの ID

戻り値： { threadId, tags }。tags は { id, name, color } の配列です。

set_thread_tags

スレッドにタグを設定します。この単一のツールで、タグの設定、更新、削除を行えます。渡したタグのセットで、スレッドの既存のタグが置き換えられます。

Parameter	Type	Required	Description
threadId	string	Yes	タグを設定するスレッドの ID
tagNames	string[]	Yes	スレッドに設定するタグ名の完全なセット。既存のタグを置き換えます（追加ではありません）。存在しない名前は自動的に作成されます。すべてのタグを削除するには [] を渡します。

動作：

• 名前の前後の空白は削除され、空の項目は除外されます。また、大文字と小文字を区別せずに重複が削除されます（"Growth" と "growth" は同じタグです）。
• 新しいタグ名は、スレッドのワークスペースの範囲内で自動的に作成されます（チームスレッド → チームタグ、個人スレッド → 個人タグ）。色は自動的に割り当てられます。
• タグ名は 40 文字までです。

戻り値： { threadId, tags } — スレッドに設定された最終的なタグのセットです。

例 — スレッドにタグを付ける：

{
  "threadId": "abc123",
  "tagNames": ["growth", "product launch"]
}

例 — すべてのタグを削除する：

{
  "threadId": "abc123",
  "tagNames": []
}

---

分析

すべての分析ツールには providerUserId（list_providers で取得）が必要です。また、アクセス範囲を指定するために、オプションで teamId を指定できます。

有料プランが必要です： get_metric_timeseries、get_post_analytics、get_follower_growth、get_best_time_to_post を利用するには、有料プラン（ユーザーまたはチームオーナー）が必要です。無料プランのユーザーには、次のメッセージが表示されます："分析にアクセスするには有料プランが必要です。https://blacktwist.app#pricing でご登録ください。"。残りのツール（get_live_metrics、get_consistency、get_daily_recap、get_recommendations）はすべてのプランで利用できます。

日付範囲： from と to の日付は両方とも範囲に含まれます。たとえば、from: "2026-03-01" と to: "2026-03-08" を指定すると、3 月 1 日から 3 月 8 日の終わりまでのすべてのデータが含まれます。

get_live_metrics

前の期間と比較した変化率を含むエンゲージメント指標を取得します。

パラメーター	型	必須	説明
providerUserId	string	はい	プロバイダーユーザー ID
from	string	いいえ	開始日（デフォルトは 7 日前）
to	string	いいえ	終了日（デフォルトは現在）
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

戻り値： views、likes、replies、reposts、quotes。それぞれに value と percentageChange が含まれます。

get_metric_timeseries

特定の指標の日次データポイントを、日付範囲を指定して取得します。

パラメーター	型	必須	説明
providerUserId	string	はい	プロバイダーユーザー ID
metric	enum	はい	次のいずれか：VIEWS、LIKES、REPLIES、REPOSTS、QUOTES、ENGAGEMENT_RATE、FOLLOWERS_COUNT
from	string	はい	開始日（ISO 8601）
to	string	はい	終了日（ISO 8601）
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

get_post_analytics

指定した期間内の投稿ごとのエンゲージメント指標を取得します。各投稿にはスレッドの続き（自分の投稿への返信）も含まれるため、複数投稿からなるスレッド全体が返されます。

Parameter	Type	Required	Description
providerUserId	string	Yes	プロバイダーユーザー ID
from	string	Yes	開始日（ISO 8601）
to	string	Yes	終了日（ISO 8601）
includeThreadParts	boolean	No	各投稿のスレッドの続き（自分の投稿への返信）をthread配列に含めます。既定値はtrueです。省略するにはfalseを指定します。
sortBy	enum	No	100 件の上限を適用する前に投稿を並べ替えます。timestamp、views、likes、replies、reposts、quotes、engagementRateのいずれかを指定します。既定値はtimestampです。
sortOrder	enum	No	ascまたはdescを指定します。既定値はdescです。
search	string	No	テキストにこの文字列が含まれる投稿のみを返します（大文字と小文字は区別せず、最大 200 文字）。
tagNames	string[]	No	これらのタグのいずれかが付いた投稿のみを返します（list_tagsのタグ名を指定。大文字と小文字は区別せず、最大 50 件）。不明な名前を指定するとエラーになります。
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントの場合は"personal"を指定します。

戻り値： posts、count（返された投稿数）、total（フィルターに一致する期間内の投稿数）。並べ替えとフィルターは、100 件の上限を適用する前に期間全体に対して適用されます。そのため、期間内に数千件の投稿がある場合でも、sortBy: "views"を指定すると実際に閲覧数の多い投稿が返されます。sortByを指定しない場合は、最も新しい投稿 100 件が返されます。total > countの場合、一覧は上限に達しています。

各投稿には、mediaId、text（200 文字に切り詰め）、timestamp、permalink、provider、analytics（views、likes、replies、reposts、quotes、engagementRate）が含まれます。また各投稿には、ユーザー自身の投稿への返信から再構成された、スレッドの続きの投稿を格納するthread配列も含まれます。これにより、複数投稿からなるスレッドのすべての投稿が返されます。各パートには、replyId、text（200 文字に切り詰め）、permalink、timestamp、partOrder（2から開始。ルート投稿はパート 1）、およびパートごとのanalytics（views、likes、replies、reposts、quotes、engagementRate）が含まれます。単独の投稿では、threadは空になります。再構成を完全に省略してthread配列を空にするには、includeThreadParts: falseを指定します。

例：

• 過去 6 か月の投稿から上位 10 件を取得する：sortBy: "views"を指定して、先頭の 10 件を取得します。
• 特定のトピックに関する投稿：search: "morning routine"。
• 特定のタグでエンゲージメント率の高い投稿：tagNames: ["Evergreen"]、sortBy: "engagementRate"。

get_follower_growth

フォロワー数の日ごとの推移を取得します。

Parameter	Type	Required	Description
providerUserId	string	Yes	プロバイダーユーザー ID
from	string	Yes	開始日（ISO 8601）
to	string	Yes	終了日（ISO 8601）
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

Returns: 日ごとの followers データポイントと totalGrowth。

get_consistency

365 日間の投稿頻度ヒートマップを取得します。

Parameter	Type	Required	Description
providerUserId	string	Yes	プロバイダーユーザー ID
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

Returns: days（{ date, count } の配列）、totalPosts、daysWithPosts、currentStreak、recordStreak。

get_daily_recap

昨日の概要を取得します。

Parameter	Type	Required	Description
providerUserId	string	Yes	プロバイダーユーザー ID
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

Returns: date、newFollowers、postsCount。

get_recommendations

分析パターンに基づく投稿のおすすめを取得します。

Parameter	Type	Required	Description
providerUserId	string	Yes	プロバイダーユーザー ID
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームを使用します。個人アカウントの場合は "personal" を渡します。

Returns: bestPostingHoursUtc、topPerformingPosts、currentStreak、recordStreak。

get_best_time_to_post

直近10週間の過去のエンゲージメントに基づいて、投稿に最適な時間帯を取得します。「投稿に最適な時間帯」の分析グラフを反映しており、エンゲージメントを時間帯別に集計します。週全体の平均と曜日ごとの内訳の両方を確認できます。時間はユーザー自身のタイムゾーンで表示されます。

有効なサブスクリプションが必要です： このツールを利用するには、有効なサブスクリプションが必要です。ユーザー自身が有料プランに加入しているか、所有者が有効なサブスクリプションに加入しているチームに所属している必要があります。それ以外の場合は、次のメッセージが返されます： "The best time to post requires an active subscription. You need your own paid plan, or to be part of a team whose owner has an active subscription. Subscribe at https://blacktwist.app#pricing"

タイムゾーン： ユーザーの notificationsTimezone 設定からサーバー側で自動的に解決されます（デフォルトは UTC）。通常、MCP の呼び出し元はユーザーのタイムゾーンを把握できないため、timezoneOffset は設定せず、自動的に導出されるようにしてください。

パラメーター	型	必須	説明
providerUserId	string	はい	プロバイダーのユーザー ID
timezoneOffset	number	いいえ	時間帯の集計に使用するタイムゾーンの上書き値です。未設定の場合は、ユーザーに設定されたアカウントのタイムゾーンが使用されます（推奨）。設定する場合は、JavaScript の Date.getTimezoneOffset() と同じ分単位の値を使用します（UTC より東の場合：UTC+2 は -120）。
view	enum	いいえ	"average"、"daily"、または "both"（デフォルト）。返す内訳を選択します。
teamId	string	いいえ	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントの場合は "personal" を渡します。

戻り値： provider、timezone（IANA 名。オフセットを上書きした場合は "custom"）、timezoneOffsetMinutes、timezoneInfo（使用されたタイムゾーンを示す人が読めるメモ。タイムゾーンが誤っている場合にユーザーが修正できるよう、https://blacktwist.app/write?settings=notifications へのリンクを含みます）、および（view に応じて）averageView（週全体の bestHours と、24時間分の averageEngagement 値）と dailyView（7日分のデータ。それぞれに dayName、bestHour、24時間分の averageEngagement 値が含まれます）。

---

フォローアップ（自動投稿）

フォローアップシステムは、エンゲージメントのしきい値（いいね、返信、リポスト）に達した後、または一定時間が経過した後に、投稿へ自動的に返信します。

タイミング： フォローアップのジョブが評価するのは、過去24時間以内に公開された投稿のみです。1日以上前に公開されたスレッドにフォローアップを設定しても効果はなく、実行されません。投稿の公開前、または公開後1日以内にフォローアップを設定してください。

get_follow_up_templates

プロバイダーの保存済みフォローアップテンプレートを一覧表示します。

Parameter	Type	Required	Description
userProviderId	string	Yes	list_providers のプロバイダー id
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントの場合は "personal" を渡します。どのチームメンバーのテンプレートを含めるかを指定します。

get_thread_follow_up

特定のスレッドのフォローアップ設定を取得します。

Parameter	Type	Required	Description
threadId	string	Yes	スレッド ID

set_thread_follow_up

スレッドのフォローアップを設定または更新します。スレッドのフォローアップ設定全体が置き換えられます。省略したフィールドは現在の値が維持されず、デフォルトにリセットされます。

Parameter	Type	Required	Description
threadId	string	Yes	スレッド ID
isEnabled	boolean	Yes	フォローアップを有効／無効にします
text	string	No	フォローアップの返信テキスト
images	string[]	No	画像 URL
delayTimeMinutes	number	No	時間遅延トリガー（分）
delayTimeMinutesEnabled	boolean	No	時間遅延トリガーを有効にします
numberOfLikes	number	No	「いいね」のしきい値
numberOfLikesEnabled	boolean	No	「いいね」トリガーを有効にします
numberOfReplies	number	No	返信数のしきい値
numberOfRepliesEnabled	boolean	No	返信トリガーを有効にします
numberOfReposts	number	No	リポスト数のしきい値
numberOfRepostsEnabled	boolean	No	リポストトリガーを有効にします
media	object[]	No	公開 URL を使用したメディア添付（メディア添付を参照）

---

スケジュール設定

list_time_slots

プロバイダーに設定されている投稿時間枠を一覧表示します。時間枠は、優先するスケジュール時刻を定義します。

Parameter	Type	Required	Description
providerId	string	Yes	list_providers のプロバイダー id
teamId	string	No	チーム ID。指定しない場合は、アクティブなチームが使用されます。個人アカウントの場合は "personal" を渡します。

戻り値： { timeSlotHour, timeSlotMinute, weekDays } の配列です。weekDays は [0-6] で、0 は日曜日です。

---

バズ投稿テンプレート

高いパフォーマンスを発揮した投稿から抽出された、バズ投稿テンプレートのライブラリを閲覧できます。各テンプレートには、構成、使用方法、エンゲージメント指標を含む元の投稿例が含まれています。

有料プランが必要です： 以下のツールを利用するには、有効な有料プラン（ユーザー所有のプラン、Lifetime Deal、または所有者が有料プランを契約しているワークスペースへの参加）が必要です。無料プランのユーザーには、「バズ投稿テンプレートにアクセスするには有料プランが必要です」 と表示されます。

list_viral_templates

フィルタリング、フリーテキスト検索、並べ替え、ページネーションを使って、バズ投稿テンプレートを一覧表示します。

パラメーター	型	必須	説明
search	string	いいえ	フリーテキスト検索です。投稿例のテキストを対象に検索します（大文字と小文字は区別されません）。
category	string	いいえ	単一のカテゴリーで絞り込みます。list_viral_template_categories または以前のレスポンスの categories フィールドで返された値を使用してください。
sort	enum	いいえ	投稿例のエンゲージメントで並べ替えます：views（デフォルト）、likes、replies、または engagementRate。降順です。
page	number	いいえ	ページ番号です。1から始まります。デフォルトは 1 です。
pageSize	number	いいえ	1ページあたりの項目数です（1～50）。デフォルトは 20 です。50を超える値は50に調整されます。

戻り値： { templates, categories, totalCount, page, pageSize }。

各テンプレート：

フィールド	型	説明
id	string	テンプレートID
category	string	テンプレートのカテゴリー
template	string	テンプレートの構成
instructions	string	テンプレートの使用方法
exampleText	string	元のバズ投稿のテキスト
views	number	投稿例の閲覧数
likes	number	投稿例の「いいね」数
replies	number	投稿例への返信数
engagementRate	number	投稿例のエンゲージメント率（いいね数＋返信数／閲覧数）

list_viral_template_categories

利用可能なテンプレートカテゴリーを、それぞれのテンプレート数とともにすべて一覧表示します。category フィルターを指定して list_viral_templates を呼び出す前の、カテゴリー検索に便利です。

パラメーター： なし

戻り値： { categories: [{ category, templateCount }] }。カテゴリーのアルファベット順で並んでいます。

---

アカウント

get_subscription

現在のプラン、残りの投稿上限、アカウントの利用枠を取得します。

パラメーター	型	必須	説明
teamId	string	いいえ	チームIDです。指定しない場合は、現在のチームを使用します。個人アカウントの場合は "personal" を渡してください。

戻り値： planType、planName、isFreePlan、remainingPosts、limits（maxTeams、maxMembers、maxAccounts）。

get_user_settings

タイムゾーン、日付形式、自動再投稿の設定など、ユーザー設定を取得します。

パラメーター： なし

戻り値： notificationsTimezone、dateFormat、autoRepostEnabled、autoRepostDelays など。

---

一般的なワークフロー

次に空いている時間枠に投稿を予約する

1. list_providers → プロバイダー ID を取得します
2. list_time_slots → 利用可能な時間枠を確認します
3. create_post → 次の時間枠を指定して投稿を予約します

週間パフォーマンスを確認する

1. list_providers → プロバイダーユーザー ID を取得します
2. get_live_metrics → 今週と先週のデータを確認します
3. get_recommendations → 改善案を取得します

既存の投稿を編集する

1. get_thread → スレッドと投稿 ID を取得します
2. edit_post → 特定の投稿のテキスト、トピック、メディアを更新します

既存のスレッドに投稿を追加する

1. get_thread → 現在の投稿とその ID を取得します
2. edit_thread → すべての既存の投稿（ID 付き）と新しい投稿（ID なし）を渡します

フォローアップ付きの投稿を作成する

1. create_post → 投稿を作成して予約します（threadId を返します）
2. set_thread_follow_up → プロモーション用の返信を追加します

プロバイダーでデフォルトのフォローアップテンプレートがすでに有効になっている場合、create_post が自動的に追加するため、手順 2 は上書きする場合にのみ必要です。

既存のスレッドにフォローアップまたは自動再投稿を追加する

1. list_posts または list_drafts → スレッドとその threadId を確認します
2. get_follow_up_templates → プロバイダーに保存されているテンプレートの値を確認します
3. set_thread_follow_up → テンプレートのフィールドをコピーして返信を追加します
4. set_thread_auto_repost → 再投稿までの間隔を設定します（ユーザーのデフォルト設定には get_user_settings を使用します）

まだ公開されていないスレッド、または公開から 24 時間以内のスレッドで使用できます。それを過ぎると、フォローアップのジョブは投稿を参照しなくなります。

タグを使って投稿を整理する

1. create_post → 投稿を作成します（threadId を返します）
2. set_thread_tags → タグを付けます（例：["growth", "tips"]）。新しいタグ名は自動的に作成されます
3. list_tags / get_thread_tags → 既存のタグを確認するか、スレッドに付いているタグを確認します

---

プロンプト

MCP サーバーには、複数ステップのワークフローを AI アシスタントが進めるための、再利用可能な組み込みプロンプトが含まれています。Claude Desktop では、チャットで / を入力してアクセスします。Claude Code では、claude prompts を実行して一覧表示します。

weekly-report

エンゲージメント指標、人気の投稿、フォロワーの増加、推奨事項を含む週間パフォーマンスレポートを生成します。

引数：

パラメーター	必須	説明
providerUserId	はい	プロバイダーユーザー ID

例： 「Threads アカウントの weekly-report プロンプトを実行して」

content-ideas

最もパフォーマンスの高いコンテンツや投稿パターンに基づいて、投稿のアイデアを生成します。

引数：

パラメーター	必須	説明
providerUserId	はい	プロバイダーユーザー ID
topic	いいえ	注目するトピック（例："productivity"、"startups"）

例： 「マーケティングに関するコンテンツのアイデアを教えて」

optimize-schedule

投稿パターンを分析し、最適な週間投稿スケジュールを提案します。

引数：

パラメーター	必須	説明
providerUserId	はい	プロバイダーユーザー ID
providerId	はい	プロバイダー ID

例： 「投稿スケジュールの最適化を手伝って」

draft-review

現在の下書きを確認し、公開前に改善するための提案を取得します。

引数： なし

例： 「下書きを確認して、改善方法を教えて」

monthly-recap

主要な指標、人気の投稿、成長傾向を含む包括的な月次レポートを生成します。

引数：

パラメーター	必須	説明
providerUserId	はい	プロバイダーのユーザー ID

例： 「月次レポートを生成して」

---

API キーの管理

• キーを作成： Settings > MCP > Create API Key
• キーを表示： Settings > MCP（プレフィックス、作成日、最終使用日時が表示されます）
• キーを削除： キーの横にあるゴミ箱アイコンをクリックします
• エンドポイント： GET/POST/DELETE /api/user/mcp-keys

キーは保存前に SHA-256 でハッシュ化されます。作成時に生のキーが表示されるのは一度だけです。

---

認証

MCP サーバーは 2 つの認証方式に対応しています。どちらも Authorization: Bearer <token> ヘッダーを使用します。

OAuth 2.1（claude.ai および OAuth 対応クライアント向け）

サーバーは、OAuth 2.1 と PKCE（S256）を使用したMCP Authorization 仕様を実装しています。claude.ai などの OAuth 対応クライアントは、このフローを自動的に処理します。

OAuth エンドポイント：

エンドポイント	説明
GET /.well-known/oauth-protected-resource	リソースのメタデータ（RFC 9728）
GET /.well-known/oauth-authorization-server	認可サーバーのメタデータ（RFC 8414）
POST /api/mcp/oauth/register	動的クライアント登録（RFC 7591）
GET /api/mcp/oauth/authorize	認可エンドポイント
POST /api/mcp/oauth/token	トークンの交換と更新
POST /api/mcp/oauth/revoke	トークンの取り消し（RFC 7009）

仕組み：

1. クライアントは、Well-Known メタデータを通じて OAuth エンドポイントを検出します
2. クライアントは動的クライアント登録を使用して自身を登録します
3. ユーザーは BlackTwist アカウントでのサインインにリダイレクトされます（既存の BlackTwist ログインを使用します）
4. サインイン後、認可コードが発行され、アクセス トークンとリフレッシュ トークンに交換されます
5. アクセス トークンの有効期限は 1 時間です。リフレッシュ トークン（有効期間 30 日）を使用して自動的に更新されます

API キー（デスクトップクライアントおよび CLI ツール向け）

API キーは bt_mcp_ をプレフィックスとする固定トークンです。デフォルトでは有効期限がなく、OAuth に対応していないクライアント（Claude Desktop、Cursor、Claude Code CLI）に適しています。

キーの作成と管理については、API キーの管理をご覧ください。

---

技術詳細

• エンドポイント： POST /api/mcp（JSON-RPC）
• トランスポート： @modelcontextprotocol/sdk の WebStandardStreamableHTTPServerTransport
• モード： ステートレス（セッション管理なし）
• 認証： PKCE（S256）を使用する OAuth 2.1、または Authorization: Bearer <key> ヘッダーによる API キー
• 認証なしの検出： initialize と tools/list は認証なしで呼び出せるため、MCP レジストリ（例：Glama）が利用可能なツールを調査できます
• レート制限： 認証済みリクエストは IP ごとに 60 req/min、認証なしの検出リクエストは IP ごとに 10 req/min に制限されます
• ソースコード： src/libs/mcp/（server、auth、oauth、tools）、src/app/api/mcp/（ルートハンドラー、OAuth エンドポイント）