# instagram-mcp

MCP server for **organic Instagram** analytics via the Meta Graph API (no Ads API).
The Facebook Page tools live in the separate `facebook-mcp` server.

Connects every Instagram Business/Creator account linked to your Pages; tools
default to your first account and accept `ig_user_id` to target another.

## Quick start

```bash
# Windows: double-click start.bat   ·   macOS/Linux: ./start.sh   ·   or:
python launcher.py
```

Installs deps, logs in with Facebook (saving tokens), and registers `instagram`
in your Claude Desktop config. You need a Meta App ID + Secret (one-time app with
Facebook Login and redirect URI `http://localhost:8765/callback`). Each IG account
must be a Business/Creator account linked to a Facebook Page.

## Tools (read-only)

- `list_connected_accounts`, `ig_get_all_accounts_summary`, `list_available_metrics`
- `ig_get_profile`, `ig_get_media`, `ig_get_media_details`, `ig_get_media_children`, `ig_get_media_by_type`
- `ig_get_media_insights`, `ig_get_media_insights_bulk`, `ig_get_reel_insights`
- `ig_get_account_insights`, `ig_compare_account_insights`, `ig_account_overview`
- `ig_get_audience`, `ig_get_demographics`, `ig_get_reach_breakdown`, `ig_get_online_followers`
- `ig_get_media_comments`, `ig_get_comment_replies`
- `ig_get_stories`, `ig_get_story_insights`, `ig_get_live_media`
- `ig_get_top_media`, `ig_get_follower_growth`, `ig_get_engagement_rate`,
  `ig_get_content_type_performance`, `ig_get_best_time_to_post`
- `ig_search_hashtag_media`, `ig_get_recently_searched_hashtags`, `ig_get_tagged_media`, `ig_get_mentioned_media`
- `ig_business_discovery`, `ig_compare_to_competitor`
- `ig_get_profile_activity`, `ig_get_product_tags`, `ig_get_available_catalogs`, `ig_get_content_publishing_limit`
- Resource `instagram://accounts`
- Publishing (opt-in): `ig_publish_media`, `ig_reply_comment`, `ig_delete_comment`

All tools take `response_format` (markdown default / json).

## Auth & credentials

Login is shared with `facebook-mcp` — both read the same
`~/.config/meta-social-mcp/credentials.json`, so logging in from either server
sets up both. Read permissions: `instagram_basic`, `instagram_manage_insights`,
`pages_show_list`, `pages_read_engagement`, `business_management`.

```bash
python server.py login --app-id YOUR_APP_ID --app-secret YOUR_APP_SECRET
python server.py whoami
```

Publishing requires `--with-publishing` at login (adds `instagram_content_publish`,
`instagram_manage_comments`; needs Meta App Review) and `META_ENABLE_PUBLISHING=1`.

## Env knobs

`META_GRAPH_VERSION` (default v19.0), `META_CACHE_TTL`, `META_ENABLE_PUBLISHING`,
`META_PAGE_ACCESS_TOKEN`, `IG_USER_ID`, `META_SOCIAL_CREDENTIALS`.