SocialAPIs — Facebook & Instagram Data

SocialAPIs MCP サーバー

---

🚀 クイックスタート

AI エージェント（Cline、Claude Code、Cursor）： インストールと検証の手順については、llms-install.md を参照してください。

ワンクリック： 上の Cursor にインストール ボタンを使用し、Cursor の MCP 設定で YOUR_API_KEY をご自身のキーに置き換えてください。Smithery、cursor.directory、mcp.so、および公式 MCP レジストリ（io.github.SocialAPIsHub/social-media-api）にも掲載されています。

オプション A — ホスト型（リモート MCP、インストール不要）

リモート MCP サーバー（Streamable HTTP）に対応した任意のクライアントから、次の URL に接続します。

https://mcp.socialapis.io/mcp

ヘッダーに SocialAPIs API キーを指定して認証します。

Authorization: Bearer YOUR_API_KEY

（x-api-token: YOUR_API_KEY も使用できます。）ツール一覧の取得にはキーは不要ですが、ツールの呼び出しにはキーが必要です。URL とヘッダーを指定するクライアント向けの設定例：

{
  "mcpServers": {
    "socialapis": {
      "url": "https://mcp.socialapis.io/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

オプション B — ローカル（npx、stdio）

インストール

npm install -g @socialapis/mcp

設定

Claude Desktop の設定に追加します。

macOS：

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows：

notepad %APPDATA%\Claude\claude_desktop_config.json

🔧 設定

方法 1：コマンドライン引数（Claude Desktop に推奨）

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

方法 2：環境変数

# Set environment variable
export SOCIALAPIS_API_KEY=your_api_key_here

# Run without argument
npx @socialapis/mcp

方法 3：.env ファイル（開発用）

# Copy example file
cp .env.example .env

# Edit with your values
nano .env

.env ファイル：

SOCIALAPIS_API_KEY=your_api_key_here
MCP_PROXY_URL=https://mcp.socialapis.io

環境変数

変数	説明	デフォルト
SOCIALAPIS_API_KEY	SocialAPIs API キー	なし（必須）
MCP_PROXY_URL	MCP プロキシサーバーの URL	https://mcp.socialapis.io
PORT	HTTP サーバーのポート	3001
API_BASE_URL	バックエンド API の URL	https://api.socialapis.io
SOCIALAPIS_CATALOG_URL	サーバーが参照する最新のエンドポイントカタログ（サーバーのみ）	https://auth.socialapis.io/api/public/endpoints
SOCIALAPIS_CATALOG_REFRESH_MS	カタログ（サーバー）またはツール一覧（npm クライアント）を再読み込みする間隔	600000（10 分）
SOCIALAPIS_LIVE_CATALOG	0 = 常にバンドル済みの定義を使用（サーバーのみ）	有効

ライブカタログ

価格、説明、パラメーターは、新しいリリースを待たずに SocialAPIs API に準拠します。サーバーは起動時（タイムアウトは 3 s）と 10 分ごとに公開エンドポイントカタログを読み込み、src/catalogBaseline.json（src/tools.js の作成時に参照したカタログ）と比較して、変更があった部分のみを適用します。新しい価格はツールの Pricing: の文に反映され、説明やパラメーターが編集された場合はその内容が置き換わります。パラメーターが追加または削除された場合は、それぞれ追加または削除され、無効になったエンドポイントのアクションには "Currently unavailable." と表示されます。ツール名とアクション名は変更されず、新しいエンドポイントも、リリースで追加されるまではツールになりません。カタログを読み込めない場合、または変更によって 2 つのアクションのパラメーターが競合する場合は、最後に正常に取得できた定義（初回は同梱された定義）が維持されます。GET /health には catalog: { source, version, fetchedAt, routes } が表示されます。npm クライアントは 10 分ごとにツール一覧を再読み込みし、変更があった場合は notifications/tools/list_changed を送信します。

API に合わせて tools.js を更新した後、ベースラインを更新します：node scripts/snapshot-catalog.mjs --from https://auth.socialapis.io/api/public/endpoints（公開フィールドのみ）。

API キーの取得

1. socialapis.io でサインアップします
2. Dashboard に移動します
3. API キーをコピーします
4. 設定の YOUR_API_KEY を置き換えます

テスト

Claude Desktop を再起動して、次のように尋ねます：

Get Nike's Facebook page details

---

📋 機能

• 🌐 API キーは 1 つ - Facebook と Instagram を 1 つのインターフェースで利用できます
• 🤖 AI ファースト - Claude、Cursor、AI エージェント向けに構築されています
• 📊 豊富なデータ - 投稿、コメント、エンゲージメント指標
• 🔍 高度なフィルタリング - 期間、ページネーション
• 🎯 シンプルな認証 - OAuth の複雑さはありません
• 🧩 構造化出力 - すべてのツールが出力スキーマを宣言し、{ result, creditsCharged, creditsRemaining } を返すため、エージェントはクレジットの消費を直接追跡できます
• 🛡️ 読み取り専用アノテーション - すべてのツールに readOnlyHint が設定されているため、クライアントは確認プロンプトを省略できます
• ⚡ 高速 - グローバルエッジネットワーク
• 🔒 セキュア - API キーはローカルに保持されます

---

🛠️ 利用可能なツール

Facebook と Instagram を対象に、12 個のツールで 50 種類のアクションを実行できます。各ツールは 1 つのリソースをまとめており、action 引数を受け取ります。各アクションは api.socialapis.io の REST エンドポイント 1 つに対応しています。ツールの説明には各アクション、必要なパラメーター、クレジットの消費量が記載されています。

ツール	アクション
facebook_page	details（フォロワー数、連絡先情報、カテゴリ。exact_followers_count=true の場合は 5 クレジットを消費）、id、posts（limit は 3～9、日付フィルター）、videos（limit は 6～12）、reels、albums（id の profile_id、limit は 8～16）、album_items（アルバム内の写真と動画）
facebook_group	details、id、posts（limit は 3～9、日付フィルター）、videos、albums（id の group_id、limit は 8～16）、album_items
facebook_post	details、details_extended（閲覧数、動画 URL、音声メタデータ）、id、attachments（5 クレジット）、video、comments、comment_replies
facebook_search	pages、people、posts、videos、locations（他の検索で使用するロケーション UID）
facebook_ads	search（キーワード、ページ、国、ステータスによる広告検索）、keywords（キーワードに関連する広告主）、page_details、archive_details、countries
facebook_marketplace	search（価格、場所、カテゴリ、状態のフィルター）、vehicles、rentals、listing、seller、categories、city_coordinates
facebook_media_download	Facebook の画像と動画のダウンロード URL
instagram_profile	details、id、posts、reels、highlights、highlight_details
instagram_post	details、id（投稿 URL のショートコード）
instagram_reels	feed、by_audio
instagram_search	キーワードに関連する人気ユーザー、ハッシュタグ、場所
instagram_location	posts（新着または人気）、nearby

呼び出し例：{"action": "posts", "link": "https://www.facebook.com/nike", "limit": 9} を指定して facebook_page を呼び出します。

1.x からのアップグレード： 以前のエンドポイントごとのツール名（facebook_get_page_details、instagram_get_profile_posts など）も、直接呼び出せば引き続き動作するため、既存のプロンプトやスクリプトはそのまま実行できます。これらは一覧に表示されなくなりました。クライアントがツール名で自動承認する場合は、新しい名前を追加してください。

現時点で未対応

現在利用できるのは Facebook と Instagram のみです。TikTok、X / Twitter、LinkedIn、YouTube はロードマップに含まれていますが、確定した提供時期はありません。これらのツールは提供開始後にのみ、ここに掲載されます。

プラットフォームのロードマップは socialapis.io/api-sources でご確認ください。

---

💡 使用例

以下の各プロンプトは、実際の Claude Desktop セッションで使用されたものです。単一ツール呼び出しのパターン（「X を取得して」）もあれば、Claude が複数の呼び出しを連携し、結果を集計する必要があるパターンもあります（該当箇所に記載）。

単一呼び出しのパターン（高速・低コスト）

What's Nike's follower count on Facebook?
→ Uses facebook_page action=details (1 credit)

Get the latest 9 posts from facebook.com/EngenSA
→ Uses facebook_page action=posts with limit=9 (1-3 credits depending on actual returned count)

Show me the Meta ads currently running for "Apple Vision Pro" in Germany
→ Uses facebook_ads action=search (1 credit)

複数呼び出しのパターン（Claude が連携して実行します。ただし、時間とコストがかかります）

Compare engagement on Nike vs Adidas's last 9 Facebook posts
→ Claude calls facebook_page action=posts twice (~2-6 credits total),
  aggregates reactions/comments/shares per post, returns a comparison.

What are people saying in the comments on Coca-Cola's last 3 posts?
→ Claude calls facebook_page action=posts (1 credit) then
  facebook_post action=comments 3 times (3 credits) and summarizes.

Show me marketplace listings for "PlayStation 5" under $400 in Berlin
→ Claude calls facebook_marketplace action=city_coordinates (1 credit) +
  facebook_marketplace action=search with filters (1 credit).

この MCP サーバーが対応していないこと

チャットでは自然に見えるクエリ（「過去1か月のエンゲージメントを比較して」など）でも、API がまだ単一のツールとして提供していない集計が必要な場合があります。Claude は引き続き回答できますが、多数のツール呼び出しが発生するため、時間とコストがかかります。

クエリの形式	難しい理由
ページの「過去30日間のエンゲージメント率」	日付範囲内のすべての投稿を取得し（ページネーションされ、1回の呼び出しにつきlimitは最大9件）、投稿ごとのエンゲージメントを計算する必要があります。投稿数の多いページでは、LLM のツール呼び出し予算を使い切ってしまいます。
「過去1か月のブランドA、B、Cのエンゲージメント率を比較」	同じ問題が3倍発生します。ブランドごとにページネーション付きの取得を行い、その後、比較計算が必要です。短い期間なら対応できますが、投稿数の多いページで「過去1か月」を対象にすると時間がかかります。
Facebook 自体が提供する範囲より古い過去のアーカイブ	Facebook が一般公開している情報を提供します。Facebook の表示フィードから外れた投稿は取得できません。
サーバー側の時系列データ（日次エンゲージメント、週次成長率）	まだ対応していません。組み込み集計機能を備えた将来のengagement-statsエンドポイントとしてロードマップに含まれています。

ユースケースがこれらのパターンのいずれかに当てはまり、LLM によるオーケストレーションではなく、事前に集計されたデータを利用したい場合は、具体的なクエリを添えてサポートにお問い合わせください。お客様の需要に基づいて、集計エンドポイントの優先度を決定しています。

---

🏗️ アーキテクチャ

Claude Desktop
    ↓
@socialapis/mcp (local MCP client)
    ↓
https://mcp.socialapis.io (global proxy)
    ↓
https://api.socialapis.io (data API)

このアーキテクチャを採用する理由

• ✅ 低レイテンシー（グローバルエッジネットワーク）
• ✅ 高い信頼性（稼働率99.9%）
• ✅ 自動レート制限
• ✅ スマートキャッシュ
• ✅ API キーはローカルに保持されます

---

🔧 開発

ローカル環境のセットアップ

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

# Install dependencies
npm install

# Run MCP client
npm start YOUR_API_KEY

# Run HTTP proxy server
npm run serve

プロジェクト構成

mcp-server/
├── src/
│   ├── tools.js          # The 50 endpoint definitions (one per action)
│   ├── groups.js         # Groups them into the 12 listed tools
│   ├── catalogBaseline.json  # The API catalog tools.js was written against
│   ├── catalogOverlay.js # Applies live catalog changes to the definitions
│   └── liveCatalog.js    # Fetches the live catalog (startup + every 10 min)
├── scripts/snapshot-catalog.mjs  # Rewrites catalogBaseline.json
├── test/                 # node --test (npm run test:unit)
├── mcp-wrapper.js        # MCP client (runs locally)
├── server.js             # HTTP proxy server
├── package.json
├── Dockerfile
└── README.md

テスト

# Unit tests
npm run test:unit

# Test MCP client locally
node mcp-wrapper.js YOUR_API_KEY

# Test HTTP proxy
curl http://localhost:3001/health
curl http://localhost:3001/tools

# Test specific tool
curl -X POST http://localhost:3001/proxy \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool":"facebook_page","arguments":{"action":"details","link":"https://facebook.com/nike"}}'

---

📊 料金

プラン	月間クレジット数	料金
無料	200	$0
Pro	1,500	$4.99
Ultra	30,000	$49
Mega	120,000	$179
Enterprise	カスタム	お問い合わせ

ほとんどのツールは1回の呼び出しにつき1クレジットを消費します。正確な料金は各ツールの説明に記載されています。現在のプランについては、socialapis.io/pricingをご覧ください。

詳細な料金を見る →

---

🤝 コントリビューション

コントリビューションを歓迎します。詳細はCONTRIBUTING.mdをご覧ください。

コントリビューションの簡単な手順

1. リポジトリをフォークします
2. 機能ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. プルリクエストを作成します

---

📖 ドキュメント

• ドキュメント全文
• API リファレンス
• MCP ガイド
• サンプル
• エージェントスキル：Claude Code、Cursor、Codex などのコーディングエージェントに SocialAPIs の使い方を教えます（npx skills add SocialAPIsHub/skills）

---

💬 サポート

• 📧 メール： [email protected]
• 💬 Discord： discord.gg/D5bQskrwV
• 🐛 問題の報告： GitHub Issues
• 📚 ドキュメント： docs.socialapis.io

---

🗺️ ロードマップ

リリース済み：

• Facebook API のサポート — 7 個のツール、37 個のアクション（ページ、グループ、投稿、検索、広告ライブラリ、マーケットプレイス、メディア）
• Instagram のサポート — 5 個のツール、13 個のアクション（プロフィール、投稿、リール、ハイライト、ディスカバリー／場所）
• MCP サーバーの実装
• HTTP プロキシサーバー
• npm パッケージを公開 — @socialapis/mcp
• MCP レジストリへの掲載 — registry.modelcontextprotocol.io
• Python SDK — PyPI の socialapis-sdk（50 個のエンドポイント、MIT）
• JavaScript / TypeScript SDK — npm の socialapis-sdk（Node 18 以降、Bun、Deno、ブラウザー）
• Go SDK — github.com/SocialAPIsHub/socialapis-go（慣用的な記法、依存関係ゼロ）
• エージェントスキル — Claude Code、Cursor、Codex などのコーディングエージェント向け github.com/SocialAPIsHub/skills

今後の予定：

• TikTok のサポート
• X（Twitter）のサポート
• LinkedIn のサポート
• YouTube のサポート
• 高度な分析 — サーバー側の集計エンドポイント（エンゲージメントの経時変化、ブランド比較など）により、複数回の呼び出しが 1 回のツール呼び出しで済むようにします
• リアルタイム Webhook — 新しい投稿やエンゲージメントのしきい値に達した際のプッシュ通知
• LangChain との統合

プラットフォームの優先順位は、顧客の需要に応じて変わります。優先順位を上げるには、ユースケースを添えて [email protected] にメールするか、Telegram で @socialapis に DM を送るのが最も早い方法です。

---

📄 ライセンス

このプロジェクトは MIT License のもとでライセンスされています。詳細については、LICENSE ファイルをご覧ください。

---

🙏 謝辞

• Model Context Protocol を使用して構築
• Anthropic Claude を活用
• AI エージェントコミュニティから着想を得ました

---

📇 掲載先

公式 MCP レジストリ、Smithery、LobeHub、mcp.so、mcpservers.org、cursor.directory、awesome-remote-mcp-servers にも掲載されています。

---

🌟 スターの履歴

---