Social Analytics MCP Server

A Model Context Protocol (MCP) server for Instagram and Facebook analytics via the Meta Graph API.

Features

Instagram

• Account discovery and profile information

• Account-level insights with demographic breakdowns

• Media listing with engagement data

• Per-post insights (images, videos, reels, carousels)

• Stories retrieval

• Hashtag search and media discovery

• Content publishing rate limits

• Mentioned/tagged media

Facebook

• Page discovery and detailed page info

• Page-level insights (impressions, engagement, fans, views)

• Post-level insights

• Posts with inline metrics

• Page feed with reactions/comments/shares

• Known metrics reference

• Access token validation

Shared

• Pre-built analysis prompts for common workflows

• Retry with exponential backoff on 429/5xx errors

• Structured error handling across both platforms

• Debug logging via DEBUG=social-analytics-mcp

Quick Start

1. Install and build

   git clone <repository-url>
   cd social-analytics-mcp
   npm install
   npm run build

2. Get an access token from the Graph API Explorer with permissions:

   • Instagram: instagram_basic, instagram_manage_insights, pages_read_engagement

   • Facebook: read_insights, pages_read_engagement

3. Add to your MCP client (see configuration below)

Configuration

You only need to configure access tokens for the platforms you want to use. Account and page IDs can be discovered using the built-in tools.

MCP Client Setup

Claude Desktop

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "social-analytics": {
      "command": "node",
      "args": ["/absolute/path/to/social-analytics-mcp/dist/index.js"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_token_here",
        "FACEBOOK_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Claude Code

claude mcp add social-analytics node /absolute/path/to/social-analytics-mcp/dist/index.js \
  -e INSTAGRAM_ACCESS_TOKEN=your_token_here \
  -e FACEBOOK_ACCESS_TOKEN=your_token_here

Available Tools

Instagram Tools

Facebook Tools

Common Parameters

Most Instagram tools accept an optional account_id parameter. If not provided, the account is auto-detected from the INSTAGRAM_ACCOUNT_ID environment variable or discovered automatically if only one account exists.

Most Facebook tools accept an optional page_id parameter with similar auto-detection behavior via FACEBOOK_PAGE_ID.

Available Prompts

Programmatic Usage

import { InstagramClient, FacebookClient, createServer } from 'social-analytics-mcp';

// Use clients directly
const instagram = new InstagramClient({
  accessToken: 'your_token',
  accountId: 'optional_account_id',
});
const profile = await instagram.getUserProfile();

// Or create an MCP server programmatically
const server = createServer();

Troubleshooting

"Access token is invalid"

• Ensure your token has the required permissions

• Short-lived tokens expire in 1 hour — generate a long-lived token

"No Instagram Business account found"

• Your Instagram account must be a Business or Creator account

• It must be connected to a Facebook Page

"Unsupported metric"

• Some metrics are media-type specific (e.g., avg_time_watched only works for videos/reels)

• Use facebook_list_known_metrics to see supported Facebook metrics

Rate limits

• Instagram: 200 calls/hour per user token

• The server automatically retries on 429/5xx with exponential backoff

Contributing

See CONTRIBUTING.md for development setup and guidelines.

License

MIT

Note: This is an unofficial tool and is not affiliated with Meta, Facebook, or Instagram.