PostMCP AI

PostMCP AI Model Context Protocol (MCP) サーバー

公式の PostMCP AI Model Context Protocol（MCP）サーバーです。ソーシャルメディアへの投稿ワークフローを、Claude Desktop、Claude.ai、Cursor、ChatGPT Custom GPTs などの AI アシスタント、デスクトップアプリ、IDE のワークフロー、ウェブ環境に直接接続します。

対応プラットフォームには、LinkedIn、X (Twitter)、Facebook、Instagram、Threads、Bluesky、YouTube Shorts があります。

---

🚀 機能と能力

• 🤖 組み込みツール 20 個：ワークスペース、接続済みアカウントとそのトークンの状態、投稿キュー、事前チェック、作成／予約／再予約／公開／再試行／削除、投稿ごとおよびプロフィールごとの分析、メディアのアップロード、画像生成、一括処理。
• 🖼️ カルーセルとギャラリー：mediaUrls を渡すと、Instagram と Threads ではカルーセル、Facebook と LinkedIn では複数写真の投稿、X と Bluesky では 4 枚の画像ギャラリーを公開できます。1 回の呼び出しで、各ネットワークの上限を事前に確認します。
• ⚡ 2 種類のトランスポートモード：ネイティブの Stdio モード（ローカルのデスクトップアプリと IDE 向け）と Streamable HTTP モード（ウェブサービス、Claude.ai、リモートコネクター向け）。
• 🔑 柔軟な認証：環境変数（POSTMCPAI_API_KEY）、URL クエリパラメーター（?apikey=YOUR_KEY）、HTTP 認証ヘッダー（x-api-key、Bearer token）から API キーを自動検出します。
• 🗂️ 複数のワークスペースに対応：API キーには専用のワークスペースが設定されているため、キーを指定するだけで利用できます。別のワークスペースを操作する場合、すべてのツールで省略可能な workspaceId を指定できます。接続ごと（?projectId=...、x-project-id）またはプロセスごと（POSTMCPAI_PROJECT_ID）にも設定できます。
• 🤖 ChatGPT Actions に対応：組み込みの OpenAPI 3.0 仕様ジェネレーター（/openapi.json）と REST エンドポイント（/api/tools/:name）が含まれており、ChatGPT Custom GPT との統合に利用できます。
• 🔒 PKCE および RFC 9728 による OAuth：ユーザーごとの同意、暗号化された権限付与の永続化、トークンのローテーション、ChatGPT／Codex 向け DCR に対応しています。OAUTH.md に記載された本番環境の設定が必要です。API キーを使用するクライアントも引き続き利用できます。
• 🧩 インストール可能なプラグイン：アカウントのオンボーディング、投稿、予約、分析のワークフローに対応しています。PLUGIN.md を参照し、npm run package:plugin を実行してください。

---

📁 リポジトリーのアーキテクチャ

mcp-server/
├── bin/
│   └── cli.js            # Executable CLI entry point (Stdio / HTTP mode runner)
├── src/
│   ├── config.js         # Centralized configuration & environment loader
│   ├── client.js         # Backend API client, API key & workspace extraction
│   ├── platforms.js      # Platform limits, credit pricing & post cost helper
│   ├── tools/
│   │   ├── definitions.js# MCP tool JSON schemas & parameter specifications
│   │   ├── handlers.js   # MCP tool execution handlers
│   │   └── index.js      # Tool definitions aggregator
│   ├── server.js         # MCP Server instance factory
│   ├── routes/
│   │   ├── oauth.js      # OAuth 2.0 & RFC 9728 discovery endpoints
│   │   ├── openapi.js    # OpenAPI 3.0 schema & ChatGPT REST endpoints
│   │   ├── mcpHttp.js    # MCP Streamable HTTP transport (/mcp)
│   │   └── health.js     # Health check & system metadata endpoints
│   ├── app.js            # Express application factory
│   └── index.js          # Main library entry point
├── index.js              # Executable wrapper script
├── package.json
└── README.md

---

⚙️ 環境設定

環境変数	説明	デフォルト値
POSTMCPAI_API_KEY	必須。 PostMCP AI ダッシュボードで取得した秘密の API キーです。	None
POSTMCPAI_API_URL	バックエンド API のルートです。セルフホストまたはローカルのバックエンドを使用する場合にのみ設定してください。	https://api.postmcpai.com
POSTMCPAI_PROJECT_ID	省略可能。API キーに紐付けられたワークスペースを上書きします。呼び出し時に workspaceId を指定すると、さらに上書きされます。	API キーの発行元ワークスペース
PORT	設定すると、サーバーが リモートの Streamable HTTP モードで起動します。	None（デフォルトは Stdio モード）

---

🛠️ MCP ツールリファレンス

以下の各ツールでは、特定のワークスペースを操作するために、list_workspaces で取得した workspaceId も省略可能な引数として指定できます。

閲覧

ツール名	説明	必須	任意
get_user_info	認証済みユーザーのプラン、クレジット残高、アクティブなワークスペース、ロールです。	—	workspaceId
list_workspaces	ユーザーが所属するすべてのワークスペースと、ID、ロール、接続済みプラットフォームです。	—	—
get_connected_accounts	接続済みのソーシャルプロフィールと、対象指定に必要な profileId です。	—	workspaceId
get_account_health	トークンの有効期限が切れている、または間近で、再接続が必要な接続です。	—	workspaceId
get_profile_analytics	接続済みプロフィールのフォロワー数、フォロー数、投稿数、ネットワーク上の閲覧数です。保存済みデータの閲覧は無料です。refresh を指定すると、ネットワークから現在のデータを1クレジットで取得します。	platform、profileId	refresh
list_posts	投稿キューを新しい順に表示し、プロフィールごとの配信状況、ページネーション、件数を返します。	—	status、page、limit、all
get_post	1件の投稿の詳細です。投稿を受け取ったプロフィール、公開 URL、プロフィールごとのエラーを確認できます。	id	—
get_post_analytics	プロフィールごとの閲覧数、いいね数、コメント数、シェア数、保存数、クリック数と、プラットフォームの生の指標です。保存済みデータの閲覧は無料です。refresh を指定すると、ネットワークから現在のデータを1クレジットで取得します。	id	refresh

作成

ツール名	説明	必須	任意
preflight_post	ドライランを実行します。文字数制限、未接続のプロフィール、メディアの不足、カルーセルの上限、クレジット消費量を確認します。投稿は公開されません。	content	targetAccounts、platforms、mediaUrl、mediaUrls
create_post	指定したプロフィールへの投稿を、下書き、予約、または即時公開します。プロフィールごとに個別の投稿が作成され、それぞれに固有の ID が付与されます。複数の mediaUrls を指定すると、カルーセルとして公開されます。	content	targetAccounts、variants、platforms、publishImmediately、scheduleDate、scheduleTime、timezone、mediaUrl、mediaUrls、youtube
publish_post_now	既存の投稿を即時公開します。失敗した投稿を再試行する場合も、配信済みのプロフィールはスキップします。	id	—
update_post	投稿の内容、対象プロフィール、スケジュール、メディア、ステータスを更新します。mediaUrls を指定すると、添付ファイル全体が置き換わります。	id	content、targetAccounts、platforms、scheduleDate、scheduleTime、timezone、mediaUrl、mediaUrls、youtube、status
reschedule_post	投稿内容と対象を維持したまま、投稿を新しい時間枠に移動します。失敗した投稿と下書きの投稿も再度有効になります。	id、scheduleDate、scheduleTime	timezone
reset_stuck_post	公開処理の途中で停止した投稿を解放し、再試行できるようにします。配信済みプロフィールの状態は維持されます。	id	force
delete_post	予約済みまたは失敗した投稿をキャンセルして削除します。	id	—
generate_image	投稿用画像を生成し、mediaUrl に使用できるホスト済み URL を返します。20クレジットを消費します。有料プランのみ利用できます。	prompt	styleImageUrl
create_media_upload_url	画像または動画の直接アップロードを許可します。署名付き PUT URL と、アップロード後に使用する公開 URL を返します。	fileName、contentType、fileSize	workspaceId
complete_media_upload	アップロードに成功したファイルをメディアライブラリに登録し、mediaUrl を返します。	url、key、fileName、contentType、fileSize	workspaceId
import_media_from_url	公開されている画像または動画をストレージとメディアライブラリにコピーし、mediaUrl を返します。	url	workspaceId

メディアのアップロード

ローカルファイルの場合、MCP クライアントには HTTP アップロード機能が必要です。

1. fileName、contentType（MIME タイプ）、fileSize（バイト単位）を指定して create_media_upload_url を呼び出します。例：{ "fileName": "launch.png", "contentType": "image/png", "fileSize": 245760 }。
2. 返された headers を使って、ファイルの生バイトデータを返された uploadUrl に PUT します。PostMCP API キーをストレージに送信しないでください。URL は expiresIn 秒後に期限切れになります（通常は 900 秒）。期限切れになった場合は、別の URL をリクエストしてください。URL を作成しただけでは、ファイルはアップロードされません。
3. PUT の成功後、返された publicUrl を url として、返された key と同じファイルメタデータを指定して complete_media_upload を呼び出します。両方のツールで同じ workspaceId を使用してください。これによりファイルが登録されますが、バイトデータの転送や検証は行われません。
4. 返された mediaUrl を create_post または update_post で使うか、複数の URL を mediaUrls にまとめてカルーセルに使用します。

公開済みのファイルがある場合は、{ "url": "https://example.com/launch.png" } を指定して import_media_from_url を呼び出します。バックエンドがファイルをダウンロードし、1 回の呼び出しで保存先の mediaUrl を返します。URL は認証なしでファイルを直接配信する必要があります。プライベートネットワークの URL はバックエンドによって拒否されます。

ストレージが対応する形式は PNG、JPEG、GIF、WebP、AVIF、HEIC、MP4、MOV、WebM、M4V で、画像の上限は 25 MiB、動画の上限は 512 MiB です。ソーシャルプラットフォームごとに、より厳しい公開要件が設定されています。公開前に preflight_post を使用してください。ファイルのバイトデータや base64 が MCP JSON リクエストを経由することはありません。ストレージへの保存後にライブラリへの登録に失敗した場合、結果には librarySaved: false と警告が含まれますが、使用可能な mediaUrl は保持されます。

バッチ処理

ツール名	説明	必須	任意
multicall	上記のツールを最大 20 個、順番に 1 回のリクエストで実行します。実行前にツール名が検証されるため、入力ミスがあってもバッチの一部だけが書き込まれることはありません。入れ子にはできません。	calls	stopOnError、workspaceId

{
  "calls": [
    { "id": "img", "tool": "generate_image", "arguments": { "prompt": "launch banner" } },
    {
      "tool": "create_post",
      "arguments": {
        "content": "We shipped it 🚀",
        "targetAccounts": [
          { "platform": "linkedin", "profileId": "lin_7741903" },
          { "platform": "twitter", "profileId": "tw_1293847", "content": "We shipped it 🚀" }
        ],
        "scheduleDate": "2026-09-01",
        "scheduleTime": "10:00",
        "timezone": "Asia/Kolkata"
      }
    }
  ],
  "stopOnError": true
}

応答には各呼び出しに対応するエントリ（{ id, tool, ok, result } または { id, tool, ok: false, error }）に加えて、件数と、エラーによってバッチが停止した場合はスキップされた呼び出しが含まれます。

カルーセル

mediaUrls は順序付きの添付ファイルのセットです。URL が 1 つの場合は通常のメディア投稿となり、2 つ以上の場合は YouTube 以外のすべてのネットワークでマルチメディア投稿として公開され、最初の URL がカバーになります。

プラットフォーム	1 投稿あたりのアイテム数	複数アイテムのセットに動画を含められるか	投稿形式
Instagram	2～10	はい	カルーセル
Threads	2～20	はい	カルーセル
Facebook	最大 10	いいえ	複数写真の投稿
LinkedIn	最大 20	いいえ	複数画像の投稿
X / Twitter	最大 4	いいえ	1 件のツイートにギャラリーとして表示
Bluesky	最大 4	いいえ	1 件の投稿にギャラリーとして表示
YouTube	1	—	1 回のアップロードにつき動画 1 本

{
  "content": "Five things we learned shipping v2 👉",
  "targetAccounts": [
    { "platform": "instagram", "profileId": "17841400000000" },
    { "platform": "threads", "profileId": "9988776655" },
    { "platform": "twitter", "profileId": "tw_1293847",
      "mediaUrls": ["https://cdn.example.com/v2/1.png", "https://cdn.example.com/v2/2.png", "https://cdn.example.com/v2/3.png", "https://cdn.example.com/v2/4.png"] }
  ],
  "mediaUrls": [
    "https://cdn.example.com/v2/1.png",
    "https://cdn.example.com/v2/2.png",
    "https://cdn.example.com/v2/3.png",
    "https://cdn.example.com/v2/4.png",
    "https://cdn.example.com/v2/5.png"
  ],
  "scheduleDate": "2026-09-01",
  "scheduleTime": "10:00",
  "timezone": "Asia/Kolkata"
}

• カルーセルに動画を混在させられるのは Instagram と Threads のみです。それ以外では、複数アイテムのセットは画像のみで構成する必要があり、動画は単独で投稿されます。
• create_post は、対象が受け付けないセットをクレジット消費前に拒否し、プロフィール名とルールを示します。同じ mediaUrls を使った preflight_post でも、同じ内容に加えて mediaSetLimits マップが報告されるため、1 つのカルーセルを複数のネットワークに投稿する場合は、事前に確認してください。
• プロフィールごとに、targetAccounts エントリに独自の mediaUrls を設定するか、variants に { "twitter": { "mediaUrls": [...] } } のように指定して、共通のセットを置き換えられます。これにより、長いカルーセルから X と Bluesky 向けに 4 枚のスライドを選べます。
• 単一の添付ファイルと同様、各スライドは書き込み時に PostMCP 独自のストレージにコピーされるため、ホスト側で後からリンクの有効期限が切れても、スケジュール済みの投稿には影響しません。公開時にスライドが 1 枚でも失敗すると、そのプロフィールの投稿は短いカルーセルとして公開されるのではなく失敗となり、publish_post_now は再試行します。
• mediaUrls を指定した update_post はセット全体を置き換えます（スライドの追加、削除、並べ替え）。空の配列を指定すると、すべてのメディアが削除されます。list_posts / get_post が返すすべての投稿には、mediaUrl とともに mediaUrls が含まれます。

クライアント向けの注意事項

• プラットフォームではなく、ターゲットプロフィールを指定してください。 targetAccounts は指定したプロフィールにのみ送信します。一方、platforms は各プラットフォームで接続されているすべてのプロフィールに配信します。
• プロフィールごとに1件の投稿です。 create_post はターゲットプロフィールごとに個別の投稿を保存するため、それぞれ独立して編集、再試行、キャンセルできます。プロフィールごとの文面は targetAccounts[].content または variants マップで指定してください。
• 現地時刻が重要な場合は、必ず timezone を渡してください。 バックエンドのデフォルトは UTC です。そのため、タイムゾーンを指定せずに IST の午前9時の投稿を予約すると、IST の午後2時30分に配信されます。
• クレジットは配信先プロフィールごとに消費されます（X/Twitter は5、それ以外は1）。また、投稿文にリンクが含まれる場合は、一度だけ50クレジットが追加で消費されます。確定前に preflight_post でこの料金を確認できます。
• アナリティクスはリクエスト時にのみ読み込まれ、バックグラウンドでは取得されません。 list_posts と get_connected_accounts は、前回取得時に保存されたデータを返し、無料です。get_post_analytics（1件の投稿について、投稿先のすべてのネットワーク）と get_profile_analytics（接続済みプロフィール1件のフォロワー数、投稿数、閲覧数）は、refresh: true を指定するとネットワークから最新データを取得し、それぞれ1クレジットを消費します。指定しない場合は、保存済みのデータを無料で返します。engagements はすべてのネットワークで「いいね」＋コメント＋シェアを表すため、プラットフォーム間で比較できます。null はネットワークがその指標を報告していないことを意味します（Bluesky には閲覧数がありません）。再接続を促す error は、そのアカウントがインサイト権限の導入前に作成されており、所有者による再接続が必要であることを示します。unavailable: true は、その種類の投稿についてネットワークが情報を返さないことを意味します（LinkedIn の個人プロフィール）。

---

💻 クライアント統合ガイド

1. Claude Desktop アプリ（Stdio モード）

以下の設定を Claude Desktop の設定ファイルに追加してください。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postmcpai": {
      "command": "npx",
      "args": ["-y", "@postmcpai/server"],
      "env": {
        "POSTMCPAI_API_KEY": "pmcp_sec_your_secret_api_key_here"
      }
    }
  }
}

---

2. Cursor IDE

1. Cursor Settings -> Features -> MCP を開きます。
2. + Add New MCP Server をクリックします。
3. 以下の情報を入力します。
   • Name：postmcpai
   • Type：command
   • Command：npx -y @postmcpai/server
4. Environment Variables で、以下を追加します。
   • POSTMCPAI_API_KEY = pmcp_sec_your_secret_api_key_here
5. Save をクリックします。

---

3. Claude.ai とリモート Web コネクター（Streamable HTTP / SSE モード）

このサーバーを任意のクラウドサービス（Render、Railway、Fly.io、Vercel）でホストするか、ngrok を使ってローカルマシンにトンネルを作成してください。

HTTP モードでの起動：

export PORT=3000
# Each remote caller supplies its own API key or OAuth token.

npm run start:sse

Claude.ai への接続：

1. API キーを付けた公開 MCP URL を指定します。 https://your-hosted-domain.com/mcp?apikey=pmcp_sec_your_secret_api_key_here
2. Claude.ai は /mcp 経由でツールの機能を検出し、シームレスに認証します。
3. この URL だけで接続できます。キーは発行元のワークスペースに紐付いているため、ツールはワークスペースを指定しなくてもそのワークスペースで動作します。同じキーを別のワークスペースで使うには、&projectId=YOUR_WORKSPACE_ID を追加するか、x-project-id ヘッダーを送信してください。個々のツール呼び出しでは、引き続き workspaceId で上書きできます。

---

4. ChatGPT カスタム GPT（REST アクション）

1. カスタム GPT アクションを設定する際に、サーバー URL（例：https://your-hosted-domain.com）を指定します。
2. 以下から OpenAPI スキーマを直接インポートします。 https://your-hosted-domain.com/openapi.json
3. 認証方式として API Key（Bearer Authorization またはカスタム x-api-key）を設定します。これは GPT Actions の統合であり、顧客ごとの OAuth プラグインではありません。プラグインには OAUTH.md を使用してください。

---

5. Node.js ライブラリのプログラムからの使用

@postmcpai/server は、独自の Node.js バックエンドでライブラリとして使用することもできます。

import { createServer, createExpressApp, makeBackendRequest } from "@postmcpai/server";

// Create a standalone MCP Server instance
const mcpServer = createServer(() => process.env.POSTMCPAI_API_KEY);

// Or create an Express app with all remote routes attached
const app = createExpressApp();
app.listen(3000);

---

🧪 ローカルでのテストと開発

# Clone the repository
git clone https://github.com/postmcp/postmcp-mcp-server.git
cd postmcp-mcp-server

# Install dependencies
npm install

# Start in Stdio Mode
npm start

# Start in HTTP Mode with hot reload
npm run dev

---

📄 ライセンス

MIT License の下で配布されています。著作権 © 2026 PostMCP AI。