本文へスキップ

MCPツールリファレンス

PostNextのMCPサーバーが提供するすべてのツールを、入力、戻り値の形式、コピーして使える例とあわせて紹介します。

MCPサーバーURLhttps://mcp.postnext.io/api
POST https://mcp.postnext.io/api

認証

https://mcp.postnext.io/apiへのリクエストには、すべてBearerトークンを含むAuthorizationヘッダーが必要です。トークンの取得方法は2つあります。

OAuth(AIクライアントにおすすめ)

AIクライアントは、初回接続時にDynamic Client Registrationを実行し、その後ユーザーをOAuthの同意画面に案内します。/mcp/connectページが、この処理を自動で行います。クライアントには、有効期間30日のアクセストークンが発行されます。

APIキー

スクリプトやCIでは、PostNextアプリの「Account → API Keys」で個人用のAPIキーを発行してください。キーはapikey_で始まり、ほかのトークンと同じくBearerトークンとして送信します。

エンドポイント

すべてのツール呼び出しは、HTTPS POSTで単一のJSON-RPC 2.0エンドポイントに送信します。

POST https://mcp.postnext.io/api

ツール

list_scheduled_posts

予約済みの投稿(投稿キューに入っていて、まだ投稿されていないもの)を一覧で返します。

引数

limitnumber ·任意 · default 20
返す結果の最大件数です(1〜100、初期値は20)。
fromstring (ISO 8601) ·任意
ISO形式のタイムスタンプです。この日時以降に予約されている投稿だけを返します。

戻り値

posts: [{id, platform, content, scheduledAt, status}]を持つオブジェクトを返します。件数はlimitまでです。

例

curl -X POST https://mcp.postnext.io/api \
  -H "Authorization: Bearer apikey_xxx" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/call","id":1,
       "params":{"name":"list_scheduled_posts",
                 "arguments":{"limit":5}}}'

list_drafts

下書き(まだ予約されていない投稿)を一覧で返します。

引数

limitnumber ·任意 · default 20
返す結果の最大件数です(1〜100、初期値は20)。

戻り値

drafts: [{id, platform, content, updatedAt}]を持つオブジェクトを返します。件数はlimitまでです。

例

{"jsonrpc":"2.0","method":"tools/call","id":2,
 "params":{"name":"list_drafts","arguments":{"limit":10}}}

list_connected_accounts

チームに連携しているSNSアカウントを一覧で返します。

引数

引数なし

戻り値

accounts: [{platform, handle, providerId, connected, lastSyncAt}]を持つオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":3,
 "params":{"name":"list_connected_accounts","arguments":{}}}

get_account_health有料プラン

連携しているすべてのSNSについて、状況のまとめを取得します。

引数

platformenum ·任意
SNSの種類です。twitter、instagram、linkedin、threads、tiktokのいずれかを指定します。
windowDays7 | 30 | 90 ·任意 · default 30
さかのぼる日数です。7、30、90のいずれかを指定します(初期値は30)。

戻り値

windowDays、postsScheduled、postsPublished、postsFailed、SNSごとの内訳(byPlatform)、topErrors[]を持つオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":4,
 "params":{"name":"get_account_health",
           "arguments":{"windowDays":30}}}

create_post_draft

新しい下書きを作成します。下書きが自動で投稿されることはありません。

引数

platformenum ·必須
SNSの種類です。twitter、instagram、linkedin、threads、tiktokのいずれかを指定します。
contentstring ·必須
投稿の本文です(1〜2,200文字)。
channelNamestring ·任意
同じSNSに複数のアカウントを連携している場合に、対象のアカウントを指定します。
providerIdstring ·任意
list_connected_accountsで取得したアカウントのproviderIdです。ユーザーネームが変わっても値は変わらないため、channelNameと一緒に、またはchannelNameの代わりに指定してください。
mediaUrlsarray<string> ·任意
画像・動画のURLを最大10件指定できます。
clientRequestIdstring ·任意
任意の冪等キーです。5分以内に同じキーを送ると、キャッシュされた結果を返します。

戻り値

新しい下書き{id, platform, content, status: "DRAFT", createdAt}を含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":5,
 "params":{"name":"create_post_draft",
           "arguments":{"platform":"twitter",
                        "content":"Hello from MCP"}}}

update_post_draft 有料プラン

既存の下書きを更新します。contentとmediaUrlsのうち、少なくとも1つを指定する必要があります。

引数

postIdstring ·必須
一覧系の呼び出しで取得した、PostNextの投稿IDです。
contentstring ·任意
投稿の本文です(1〜2,200文字)。
mediaUrlsarray<string> ·任意
画像・動画のURLを最大10件指定できます。
clientRequestIdstring ·任意
任意の冪等キーです。5分以内に同じキーを送ると、キャッシュされた結果を返します。

戻り値

更新後の下書き{id, platform, content, mediaUrls, status, updatedAt}を含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":6,
 "params":{"name":"update_post_draft",
           "arguments":{"postId":"",
                        "content":"Updated copy"}}}

connect_channel

新しいSNSを連携するために、ユーザーが開いて承認する1回限りのURLを作成します。

引数

platformenum ·必須
SNSの種類です。twitter、instagram、linkedin、threads、tiktokのいずれかを指定します。

戻り値

authUrl(ユーザーが開いて承認する1回限りのリンク)、expiresAt、platformを持つオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":7,
 "params":{"name":"connect_channel",
           "arguments":{"platform":"linkedin"}}}

schedule_post

下書き(ステータスがDRAFT)を、将来の日時で投稿キューに追加します。±60秒以内のずれは冪等に処理します。別の日時への再予約は、先に明示的にキャンセルしない限り拒否します。プランの月間投稿数に加算されます(Freeは10件で、アプリと共通)。1件の投稿は1回だけ数えるため、キャンセル後や投稿失敗後に再予約しても、再び加算されることはありません。

引数

postIdstring ·必須
一覧系の呼び出しで取得した、PostNextの投稿IDです。
scheduledAtstring (ISO 8601) ·必須
ISO 8601形式のタイムスタンプ。現在より5分以上前の時刻は指定できません。

戻り値

postId、scheduledAt(ISO)、status: SCHEDULEDを含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":8,
 "params":{"name":"schedule_post",
           "arguments":{"postId":"",
                        "scheduledAt":"2026-05-10T09:00:00Z"}}}

cancel_scheduled_post

予約済みの投稿をキャンセルし、投稿キューから外します。元の下書きは残ります。

引数

postIdstring ·必須
一覧系の呼び出しで取得した、PostNextの投稿IDです。

戻り値

postIdとstatus: CANCELLEDを含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":9,
 "params":{"name":"cancel_scheduled_post",
           "arguments":{"postId":""}}}

delete_draft

下書きを完全に削除します。DRAFT以外の投稿は削除を拒否します(SCHEDULEDの投稿にはcancel_scheduled_postを使ってください)。

引数

postIdstring ·必須
一覧系の呼び出しで取得した、PostNextの投稿IDです。

戻り値

postIdとdeleted: trueを含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":10,
 "params":{"name":"delete_draft",
           "arguments":{"postId":""}}}

get_post

指定したpostIdのPostGroup全体を、SNSごとの内容、ステータス、タイムスタンプとあわせて返します。

引数

postIdstring ·必須
一覧系の呼び出しで取得した、PostNextの投稿IDです。

戻り値

postId、status、scheduledAt、createdAt、updatedAt、providers(プラットフォーム → 内容のレコード)を含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":11,
 "params":{"name":"get_post",
           "arguments":{"postId":""}}}

search_posts

有効なチームの投稿本文を、部分一致(大文字と小文字を区別しない)で検索します。絞り込みには、status、platform、limit(1〜100、初期値は20)を使えます。

引数

querystring ·必須
検索する部分文字列(3〜200文字。正規表現のメタ文字はエスケープされます)。
statusenum ·任意
任意:DRAFT | SCHEDULED | PUBLISHED | FAILED | CANCELLED。
platformenum ·任意
SNSの種類です。twitter、instagram、linkedin、threads、tiktokのいずれかを指定します。
limitnumber ·任意 · default 20
返す結果の最大件数です(1〜100、初期値は20)。

戻り値

posts: [{postId, status, platforms, snippet, scheduledAt, updatedAt}]を含むオブジェクトを返します。snippetには一致した箇所の前後の文脈が入り、両端に省略記号が付きます。

例

{"jsonrpc":"2.0","method":"tools/call","id":12,
 "params":{"name":"search_posts",
           "arguments":{"query":"launch","limit":10}}}

list_teams

認証済みユーザーがオーナーまたは管理者であるチームを返します。現在有効なチームには印が付きます。

引数

引数なし

戻り値

currentTeamIdとteams: [{teamId, teamName, isCurrent}]を含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":13,
 "params":{"name":"list_teams","arguments":{}}}

set_current_team

このBearerトークンで使うチームを切り替えます。ユーザーは、そのチームのメンバーである必要があります。設定はOAuthトークンのドキュメントに保存され、セッション内でも変更されるため、同じ会話で続けて使うツールにすぐ反映されます。

引数

teamIdstring ·必須
list_teamsで取得した切り替え先のteamId。メンバーシップはサーバー側で再検証されます。

戻り値

teamId、teamName、persisted(OAuthの場合はtrue、APIキーの場合はfalse)、任意のnoteを含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":14,
 "params":{"name":"set_current_team",
           "arguments":{"teamId":"team_xxxxx"}}}

get_plan_limits

ユーザーの現在のプラン区分と、プランごとの上限(SNSアカウント数、ストレージ、AIクレジット、投稿)を取得します。すべてのプランで使えます。変更を伴うツールの前に呼び出すと、その呼び出しがブロックされるかどうかを予測できます。

引数

引数なし

戻り値

tier、tierDisplayName、isPaid、isTrial、limits、creditsAvailableを含むオブジェクトを返します。limitsでは、channels/storage/aiCallsがそれぞれ{limit, current, exceeded}、postsが{limit, allowed, current}の形式です。postsのcurrentは今月の件数で、読み取れなかった場合はnullです。creditsAvailableは{total, subscriptionRemaining, purchasedBalance}またはnullです。

例

{"jsonrpc":"2.0","method":"tools/call","id":15,
 "params":{"name":"get_plan_limits","arguments":{}}}

get_post_metrics

公開済みの投稿について、送信先のすべてのプラットフォームのエンゲージメント指標を取得します。Twitterはいいね、リツイート、返信、インプレッションを返し、Instagramはいいねとコメントを返します。LinkedIn、Threads、TikTokは投稿ステータスとURLのみを返します(エンゲージメントの収集は今後のリリースで対応予定です)。正規化された合計(totals)は、指標を返したプラットフォームの値を合算します。

引数

postId 一覧系の呼び出しで取得した、PostNextの投稿IDです。

戻り値

postId、status、providers: [{platform, publishedPostId, publishedUrl, publishedAt, status, metrics}]、totals: {likes, comments, shares, impressions}を含むオブジェクトを返します。metricsはプラットフォームごとの数値をまとめたオブジェクトで、そのプラットフォームがまだエンゲージメントを収集していない場合はnullです。

例

{"jsonrpc":"2.0","method":"tools/call","id":16,
 "params":{"name":"get_post_metrics",
           "arguments":{"postId":""}}}

get_publish_status

予約投稿がどうなったかを診断します。キューの状態、プラットフォームごとの成功・エラー、処理時間、ワーカーのジョブIDを確認できます。下書きとして存在していても投稿キューに移されていない投稿にはisScheduled=falseを返し、schedule_postを案内するヒントを含めます。

引数

postId 一覧系の呼び出しで取得した、PostNextの投稿IDです。

戻り値

postId、isScheduled、status、scheduledAt、publishedAt、platforms、processingTimeMs、jobId、topLevelError、results: [{platform, success, publishedPostId, publishedAt, error}]を含むオブジェクトを返します。isScheduledがfalseの場合はhintを含みます。

例

{"jsonrpc":"2.0","method":"tools/call","id":17,
 "params":{"name":"get_publish_status",
           "arguments":{"postId":""}}}

update_brand_profile 有料プラン

ユーザーの有効なブランドプロフィールを部分的に更新します。更新できるフィールドはbio、brandVoice、personalityTraits、mainThemes、expertiseAreas、preferredHashtags、audienceSizeです。それ以外のフィールドは通知なしで破棄されます。「有効」なプロフィールは、まずチームのデフォルト、次にユーザー自身の最初の有効なプロフィールの順で決まります。

引数

brandVoice ブランドの文体を表す語の配列(例:["professional", "concise"])。

Other patchable fields: bio, personalityTraits, mainThemes, expertiseAreas, preferredHashtags, audienceSize.

戻り値

profileId、name、updated: [更新したフィールド名]と、更新後のbio、brandVoice、personalityTraits、mainThemes、expertiseAreas、preferredHashtags、audienceSizeの現在の値を含むオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":18,
 "params":{"name":"update_brand_profile",
           "arguments":{"brandVoice":["professional","concise"]}}}

get_best_time_to_post 有料プラン

指定したプラットフォームで次に投稿するのに適した時間帯(dayOfWeek、hour)の上位N件を、過去90日間のデータから提案します。TwitterとInstagramは投稿あたりのエンゲージメントで、LinkedIn、Threads、TikTokは投稿頻度のみで順位を付けます。時刻は指定したIANAタイムゾーン(デフォルトはUTC)で表します。有料プランが必要です。

引数

platform SNSの種類です。twitter、instagram、linkedin、threads、tiktokのいずれかを指定します。

timezone IANAタイムゾーン名(例:Europe/Berlin、America/New_York)。デフォルトはUTCです。

topN 返す時間帯の提案数(1〜24、デフォルトは5)。

戻り値

platform、timezone、sampleWindowDays、sampleSize、metricsAvailable、recommendations: [{dayOfWeek (1-7, Mon=1), dayLabel, hour (0-23), score, basedOn: {posts, avgEngagement}}]を含むオブジェクトを返します。データが少ない初期段階や、指標を取得できない場合はhintを含みます。

例

{"jsonrpc":"2.0","method":"tools/call","id":19,
 "params":{"name":"get_best_time_to_post",
           "arguments":{"platform":"twitter","timezone":"Europe/Berlin","topN":5}}}

get_channel_analytics

連携済みのSNSアカウント1つ、またはすべてのアカウントの成果を集計します。期間中のインプレッション、リーチ、いいね、コメント、エンゲージメント率、同じ長さの直前の期間との比較、フォロワーの推移を返します。チーム全体の合計を取得するには、platformを省略してください。1件の投稿にはget_post_metricsを、予約投稿の時間選びにはget_best_time_to_postを使ってください。

引数

platform SNSの種類です。twitter、instagram、linkedin、threads、tiktokのいずれかを指定します。

channelName 同じSNSに複数のアカウントを連携している場合に、対象のアカウントを指定します。

providerId list_connected_accountsで取得したアカウントのproviderIdです。ユーザーネームが変わっても値は変わらないため、channelNameと一緒に、またはchannelNameの代わりに指定してください。

period 集計する期間です。7d、30d、90d、allのいずれかを指定します(初期値は30d)。

戻り値

scope、period、totals、vsPrevious、coverage、dataThrough、followersを持つオブジェクトを返します。followersには、trackingSince、current、change、推移のデータ(series)が入ります。

例

{"jsonrpc":"2.0","method":"tools/call","id":34,
 "params":{"name":"get_channel_analytics",
           "arguments":{"platform":"linkedin","period":"30d"}}}

search_tools

自由入力のクエリ、カテゴリ、目的でMCPツールカタログを検索します。カテゴリ、requiresScope、1行の説明、一致したユースケースタグを返します。すべてのプランで無料で使えます(ツールを探すための機能です)。

引数

すべて任意です。引数なしで呼び出すと、利用できるすべてのツールを一覧で返します。

query ツール名、説明、ユースケースタグを対象にした自由入力の検索語。

category 絞り込むカテゴリ(posts、accounts、analytics、brand、teams、discovery、otherのいずれか1つ)。

戻り値

totalTools、matchCount、categories: [string[]]、tools: [{name, category, requiresScope, description, useCases, matchedOn: [name|category|description|use_case]}]を含むオブジェクトを返します。一致するツールがない場合や、絞り込み条件がない場合はhintを含みます。

例

{"jsonrpc":"2.0","method":"tools/call","id":20,
 "params":{"name":"search_tools",
           "arguments":{"query":"why did my post fail"}}}

get_plan

プランの情報と請求日を取得します。プラン区分(tier)、更新日、トライアルの終了日、期間終了時に解約する設定かどうかがわかります。上限と使用量を確認するには、代わりにget_plan_limitsを呼び出してください。

引数

引数なし

戻り値

tier、tierDisplayName、isPaid、isTrial、gated、subscriptionStatus、renewsAt、trialEndsAt、cancelAtPeriodEnd、currencyを持つオブジェクトを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":21,
 "params":{"name":"get_plan",
           "arguments":{}}}

upload_asset

画像や動画をbase64でインライン送信し、メディアライブラリにアップロードします。確実に使えるのは、約8KB以下のごく小さなファイルだけです。それより大きいデータは、ツールの引数内で警告なく切り捨てられ、壊れたファイルが保存されます。それより大きいファイルには、request_asset_uploadを使ってください。

引数

filename 拡張子を含むファイル名です(255文字以内)。

contentType ファイルのMIMEタイプです。許可されている画像・動画の形式から指定します。

base64 base64でエンコードしたファイルのデータです。ごく小さなサイズにとどめ、先に上記の注意事項を読んでください。

戻り値

assetId、url、sizeBytes、mimeTypeを持つオブジェクトを返します。urlは、mediaUrlsとしてcreate_post_draftに渡してください。

例

{"jsonrpc":"2.0","method":"tools/call","id":22,
 "params":{"name":"upload_asset",
           "arguments":{"filename":"logo.png","contentType":"image/png","base64":"iVBORw0KGgo..."}}}

request_asset_upload

推奨のアップロード方法で、サイズを問わず画像と動画に使えます。手順は2つです。まずこのツールを呼び出して、署名付きURLとそのまま使えるcurlコマンドを取得します。次に、そのURLにファイルのデータをPUTします。PUTのレスポンスに、最終的なアセットのURLが含まれます。

引数

filename 拡張子を含むファイル名です(255文字以内)。

contentType ファイルのMIMEタイプです。許可されている画像・動画の形式から指定します。

sizeBytes ファイルの正確なサイズ(バイト)です。アップロードの署名に使います。

戻り値

uploadId、uploadUrl、uploadToken、expiresInSeconds、instructionsを持つオブジェクトを返します。instructionsには、実行するPUTコマンドがそのまま入ります。

例

{"jsonrpc":"2.0","method":"tools/call","id":23,
 "params":{"name":"request_asset_upload",
           "arguments":{"filename":"clip.mp4","contentType":"video/mp4","sizeBytes":4194304}}}

import_chat_file

ChatGPT専用です。チャットに添付された画像や動画をメディアライブラリに保存し、create_post_draftで使えるようにします。ChatGPTは各ファイルを一時的なリンクとして渡します。PostNextはそのファイルをHTTPSで一度だけダウンロードし、ファイルの中身から画像か動画かを確認します。1回の呼び出しで最大10ファイル、1ファイル50MBまでです。サイズはプランのストレージ容量に加算されます(Freeプランは合計10MB)。

引数

files チャットに添付されたファイルをもとに、ChatGPTが入力します。内容はdownload_urlとfile_idで、必要に応じてmime_typeとfile_nameも含みます。最大10件です。ほかのクライアントは、request_asset_uploadでアップロードしてください。

戻り値

filesとfailedを持つオブジェクトを返します。filesには保存できた各ファイルのassetId、url、sizeBytes、mimeType、fileNameが入り、failedには保存できなかった各ファイルのfileNameとreasonが入ります。1つも保存できなかった場合は、代わりに最初のファイルのエラーを返します。

例

{"jsonrpc":"2.0","method":"tools/call","id":35,
 "params":{"name":"import_chat_file",
           "arguments":{"files":[{"download_url":"https://files.oaiusercontent.com/...","file_id":"file_abc123"}]}}}

MCPリソース

リソースは、クライアントがMCPのresources/readメソッドで取得できる読み取り専用のコンテキストです。Claudeは会話の開始時にリソースを読み込みます。そのため、セッションのたびに説明し直さなくても、Claudeはアカウント、チーム、ブランドの情報を把握できます。

postnext://account/summary

アカウントのメールアドレスとユーザーネーム(Claudeが操作中のアカウントを確認するため)、プラン、AIクレジットの使用量と上限、下書き数、予約投稿数、連携済みSNSアカウント数。読み込みを速くするため、各件数は最大100件までです。

postnext://channels/connected

list_connected_accountsの結果と同じ形式です。リソースとして公開しているため、Claudeは会話の開始時に一度だけ読み込みます(ツール呼び出しの往復は発生しません)。

postnext://brand-profiles/active

ユーザーの有効なブランドプロフィール(チームのデフォルト。ない場合はユーザー自身の最初のプロフィール)。LLMに関係するフィールドのみを返します:bio、expertiseAreas、personalityTraits、brandVoice、mainThemes、audienceSize、preferredHashtags。

postnext://teams/current

現在のチームのメタデータ(teamId、teamName)と、利用できるチーム数(totalTeamsAvailable)。切り替えるには、list_teamsとset_current_teamを組み合わせて使います。

名前付きワークフロー

複数のツールを組み合わせて実行する、スラッシュメニューのショートカットです。1つ選ぶと、AIアシスタントが複数の手順を順に進めます。何かを変更する前には、確認を求めます。

/weekly-plan

ブランドプロフィール、連携済みのSNSアカウント、予約済みの投稿を読み取り、月曜から金曜に分散した5〜10件の下書きを提案します。

/draft-thread

指定したトピックやURLをもとに、5〜10件の投稿からなるX(旧Twitter)またはThreadsのスレッドを、ブランドボイスで作成します。

/audit-queue

今後7日間の予約投稿を確認し、重複、特定のSNSへの投稿の集中、投稿のない空白期間を指摘します。

/channel-sweep

連携済みのSNSアカウントを対応SNSの一覧と比べ、新しく連携するアカウントや再連携が必要なアカウントを提案します。

ディスカバリーとOAuthのエンドポイント

標準に準拠したメタデータを公開しているため、どのMCPクライアントでも自動で設定できます。

  • GET /.well-known/oauth-protected-resource/api — RFC 9728
  • GET /.well-known/oauth-authorization-server — RFC 8414
  • GET /oauth/.well-known/openid-configuration — OIDC
  • POST /oauth/reg — Dynamic Client Registration (RFC 7591)
  • GET /oauth/auth — Authorize (PKCE-S256 required)
  • POST /oauth/token — Token exchange

オープンソース

そのまま貼り付けて使えるレシピと開発者向けリファレンスを、公開ドキュメントリポジトリで提供しています。MITライセンスで、プルリクエストも歓迎しています。github.com/postnextio/postnext-mcp

SNS投稿のMCPサーバー(Claude・ChatGPT・あらゆるAIエージェントに対応)

PostNextのSNS投稿用MCPサーバーを使えば、Claude、ChatGPT、あらゆるAIエージェントが投稿の計画、下書き、予約投稿を行えます。下書きは、予約するまでカレンダーで待機します。