# Instagram MCP Server

An MCP server that gives AI agents access to Instagram Business account analytics and insights.

## Tools

| Tool | Description |
|------|-------------|
| `get_account_info` | Follower count, bio, media count |
| `get_recent_posts` | Recent posts with likes, comments, timestamps |
| `get_post_insights` | Deep metrics on a single post (reach, saves, shares) |
| `get_audience_info` | Follower demographics (cities, countries, age/gender) |
| `get_account_reach` | Reach and impressions over time |
| `get_top_posts` | Best performing posts sorted by engagement |

## Setup

```bash
cd instagram-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install "mcp[cli]" httpx
```

Create a `.env` file with your credentials:
```
INSTAGRAM_ACCESS_TOKEN=your_token
INSTAGRAM_ACCOUNT_ID=17841...
```

### Getting your Instagram credentials

1. Go to [Meta for Developers](https://developers.facebook.com/) and create an app (type: Business)
2. Add the **Instagram Graph API** product to your app
3. In Graph API Explorer (`developers.facebook.com/tools/explorer`):
   - Select your app from the dropdown
   - Click **Generate Access Token**
   - Grant permissions: `instagram_basic`, `instagram_manage_insights`, `pages_show_list`, `pages_read_engagement`
4. Get your Instagram Business Account ID:
   - In the Graph API Explorer, query: `me/accounts` to get your Page ID
   - Then query: `{page-id}?fields=instagram_business_account`
   - The `id` field in the response is your `INSTAGRAM_ACCOUNT_ID`
5. The token from the Explorer is short-lived (1 hour). To get a long-lived token:
   - Exchange it at: `oauth/access_token?grant_type=fb_exchange_token&client_id={app-id}&client_secret={app-secret}&fb_exchange_token={short-lived-token}`
   - This gives you a 60-day token

> **Note:** Your Instagram account must be a Business or Creator account linked to a Facebook Page.

## Usage with Claude Code

```bash
claude mcp add instagram-mcp -e INSTAGRAM_ACCESS_TOKEN=your_token -e INSTAGRAM_ACCOUNT_ID=17841... -- python3 -m src.server
```

Then ask Claude things like:
- "What are my top performing posts this month?"
- "Show me my audience demographics"
- "Which posts got the most saves?"
- "What's my engagement rate trend?"

## Content Strategist Agent

A standalone agent that analyzes your Instagram data and generates a weekly content plan with 7 post ideas, captions, and posting times.

### Running the agent

```bash
source .venv/bin/activate
python -m agent.content_strategist
```

Requires AWS credentials configured (uses Anthropic Bedrock) and the same `.env` variables as the MCP server. The agent will:

1. Pull your account info, recent posts, top posts, and audience demographics
2. Identify patterns in what's performing well
3. Generate a 7-day content plan with specific captions, hashtags, and timing
4. Save the plan as an HTML file and open it in your browser