# Instagram Analytics Mcp

> A Model Context Protocol (MCP) server that provides access to Instagram analytics and insights using the Instagram Graph API. This server allows you to retrieve account-level insights, media insights, and profile information programmatically.

- **Type:** MCP server
- **Install:** `agentstack add mcp-bilaltariq01-instagram-analytics-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BilalTariq01](https://agentstack.voostack.com/s/bilaltariq01)
- **Installs:** 0
- **Category:** [Data & Analytics](https://agentstack.voostack.com/c/data-and-analytics)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [BilalTariq01](https://github.com/BilalTariq01)
- **Source:** https://github.com/BilalTariq01/instagram-analytics-mcp

## Install

```sh
agentstack add mcp-bilaltariq01-instagram-analytics-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Social Analytics MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (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**

   ```bash
   git clone 
   cd social-analytics-mcp
   npm install
   npm run build
   ```

2. **Get an access token** from the [Graph API Explorer](https://developers.facebook.com/tools/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

| Variable | Required | Default | Description |
|---|---|---|---|
| `INSTAGRAM_ACCESS_TOKEN` | For Instagram | — | Facebook User Access Token with Instagram permissions |
| `INSTAGRAM_ACCOUNT_ID` | No | Auto-detected | Instagram Business Account ID |
| `INSTAGRAM_API_VERSION` | No | `v23.0` | Instagram Graph API version |
| `FACEBOOK_ACCESS_TOKEN` | For Facebook | — | Facebook User/Page Access Token |
| `FACEBOOK_PAGE_ID` | No | Use discovery tool | Facebook Page ID |
| `FACEBOOK_API_VERSION` | No | `v22.0` | Facebook Graph API version |
| `DEBUG` | No | — | Set to `social-analytics-mcp` for debug logs |

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`

```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

```bash
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

| Tool | Description | Required Params |
|---|---|---|
| `instagram_list_accounts` | List available Instagram Business accounts | — |
| `instagram_get_profile` | Get account profile info | — |
| `instagram_get_account_insights` | Get account-level analytics | `metrics`, `metric_type`, `period` |
| `instagram_list_media` | List recent media posts | — |
| `instagram_get_media_details` | Get details for a specific post | `media_id` |
| `instagram_get_media_insights` | Get insights for a specific post | `media_id`, `metrics` |
| `instagram_get_stories` | Get recent stories | — |
| `instagram_get_hashtag_search` | Search for a hashtag ID | `hashtag` |
| `instagram_get_hashtag_media` | Get media for a hashtag | `hashtag_id` |
| `instagram_get_content_publishing_limit` | Check publishing rate limits | — |
| `instagram_get_mentioned_media` | Get media where account is tagged | — |

### Facebook Tools

| Tool | Description | Required Params |
|---|---|---|
| `facebook_list_pages` | List accessible Facebook Pages | — |
| `facebook_get_page_details` | Get page profile information | — |
| `facebook_get_page_insights` | Get page-level insights | `metrics` |
| `facebook_get_post_insights` | Get insights for a specific post | `post_id`, `metrics` |
| `facebook_list_posts_with_insights` | List posts with inline metrics | `post_metrics` |
| `facebook_get_page_feed` | Get page feed with engagement data | — |
| `facebook_list_known_metrics` | List supported metrics reference | — |
| `facebook_validate_token` | Validate an access token | `access_token` |

### 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

| Prompt | Description |
|---|---|
| `analyze_instagram_performance` | Comprehensive Instagram account analysis |
| `analyze_facebook_performance` | Comprehensive Facebook Page analysis |
| `compare_post_performance` | Compare recent posts on either platform |
| `get_audience_demographics` | Audience demographic breakdown |
| `setup_platform` | Interactive setup guide |

## Programmatic Usage

```typescript
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](CONTRIBUTING.md) for development setup and guidelines.

## License

MIT

---

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BilalTariq01](https://github.com/BilalTariq01)
- **Source:** [BilalTariq01/instagram-analytics-mcp](https://github.com/BilalTariq01/instagram-analytics-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-bilaltariq01-instagram-analytics-mcp
- Seller: https://agentstack.voostack.com/s/bilaltariq01
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.