Instagram MCP Server

A production-ready Model Context Protocol (MCP) server for interacting with Instagram/Meta APIs. Enables AI agents to manage content, analyze performance, research competitors, and handle publishing workflows through structured MCP tools.

Features

Account Management: Profile retrieval, account insights, media listing
Content Analytics: Post, Reel, and Story insights with engagement metrics
Content Generation: Reel ideas, captions, hashtags, content calendars
Competitor Research: Profile analysis, content comparison, competitor reports
Comment Management: Classification, moderation, auto-reply workflows
Publishing Workflow: Container creation, media publishing, status tracking
Lead Scoring: Business lead analysis with scoring tiers
Audit Logging: Full request/response logging with execution metrics

Prerequisites

Python 3.10+
Meta Developer App with Instagram Graph API access
Instagram Business Account connected to your Meta App

Quick Start

1. Clone and Install

git clone <repository-url>
cd instagram-mcp
pip install -r requirements.txt

2. Configure Environment

cp .env.example .env

Edit .env with your credentials:

META_APP_ID=your_meta_app_id
META_APP_SECRET=your_meta_app_secret
INSTAGRAM_ACCESS_TOKEN=your_instagram_access_token
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id

3. Run the Server

python server.py

Docker

docker-compose up --build

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop, Cursor):

{
  "mcpServers": {
    "instagram": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "/path/to/instagram-mcp"
    }
  }
}

Available Tools

Account Tools

Tool	Description
`instagram_get_profile`	Get profile information
`instagram_get_account_insights`	Get account-level analytics
`instagram_get_media`	List media posts
`instagram_get_media_details`	Get detailed post info

Analytics Tools

Tool	Description
`instagram_get_post_insights`	Post performance metrics
`instagram_get_reel_insights`	Reel performance metrics
`instagram_get_story_insights`	Story performance metrics
`instagram_get_top_content`	Top-performing content
`instagram_compare_content`	Period-over-period comparison

Content Tools

Tool	Description
`instagram_analyze_content`	Analyze post structure
`instagram_generate_reel_ideas`	Generate Reel concepts
`instagram_generate_caption`	Generate captions with hashtags
`instagram_generate_hashtags`	Generate relevant hashtags
`instagram_generate_content_calendar`	Create multi-day calendars
`instagram_find_content_patterns`	Identify content patterns

Competitor Tools

Tool	Description
`instagram_analyze_competitor`	Analyze competitor profile
`instagram_compare_accounts`	Compare multiple accounts
`instagram_find_competitor_content`	Find top competitor content
`instagram_competitor_report`	Full competitor report

Comment Tools

Tool	Description
`instagram_get_comments`	Get and classify comments
`instagram_reply_comment`	Reply to a comment
`instagram_moderate_comments`	Moderate with classification

Publishing Tools

Tool	Description
`instagram_create_media_container`	Create publish container
`instagram_publish_media`	Publish to Instagram
`instagram_get_publish_status`	Check publish status

Lead Tools

Tool	Description
`instagram_analyze_leads`	Score and analyze leads

Example Natural Language Commands

"What were my best performing Reels last month?"
→ instagram_get_reel_insights (multiple calls) → sort → analyze → top results

"Generate a 30-day content calendar for an AI automation agency"
→ instagram_generate_content_calendar

"Analyze my competitor @examplebrand"
→ instagram_analyze_competitor → instagram_find_competitor_content

"What comments need moderation on my latest post?"
→ instagram_get_comments → classify → filter

"Compare my engagement with @competitor1 and @competitor2"
→ instagram_compare_accounts

AI Decision Layer

The server implements an internal decision pipeline:

User Request - Natural language input
Intent Detection - Determine required operation
Permission Check - Validate API access
Tool Selection - Map to appropriate MCP tool
Instagram API - Execute authorized API call
Data Validation - Validate response data
Analytics/Reasoning - Process and analyze results
Structured Response - Return formatted JSON

Comment Classification

Comments are automatically classified into:

Category	Description
`positive`	Praise, compliments, positive feedback
`negative`	Complaints, criticism, negative sentiment
`question`	Questions, inquiries
`lead`	Purchase intent, business inquiries
`spam`	Promotional spam, scam content
`support`	Support requests, issue reports
`other`	Unclassified comments

Lead Scoring

Score Range	Tier
81-100	Very High
61-80	High
31-60	Medium
0-30	Low

Scoring factors: follower count, posting frequency, business category, identified needs, website presence.

Error Handling

All tools return structured error responses:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT",
    "message": "Instagram API rate limit reached.",
    "retryable": true
  }
}

Error codes: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, RATE_LIMIT, SERVER_ERROR, NETWORK_ERROR, INVALID_MEDIA, PERMISSION_MISSING

Project Structure

instagram-mcp/
├── server.py              # Main MCP server with tool definitions
├── config.py              # Configuration management
├── requirements.txt       # Python dependencies
├── .env.example           # Environment template
├── Dockerfile             # Container configuration
├── docker-compose.yml     # Docker Compose setup
├── mcp/
│   ├── tools/             # MCP tool implementations
│   │   ├── account.py     # Account tools
│   │   ├── analytics.py   # Analytics tools
│   │   ├── content.py     # Content generation tools
│   │   ├── comments.py    # Comment management tools
│   │   ├── publishing.py  # Publishing workflow tools
│   │   └── competitors.py # Competitor research tools
│   └── schemas/           # Pydantic data models
│       ├── account.py
│       ├── content.py
│       └── analytics.py
├── services/              # Business logic layer
│   ├── instagram_api.py   # Instagram Graph API client
│   ├── analytics.py       # Analytics calculations
│   ├── content_ai.py      # Content generation engine
│   └── lead_scoring.py    # Lead analysis and scoring
├── database/              # Data persistence
│   ├── models.py          # SQLAlchemy models
│   └── repository.py      # Database operations
└── tests/                 # Unit tests
    ├── test_account.py
    ├── test_analytics.py
    ├── test_publishing.py
    └── test_errors.py

Running Tests

pytest tests/ -v

Security

OAuth 2.0 authentication via Meta Graph API
Access tokens stored in environment variables
No credential scraping or session extraction
Permission validation before operations
Rate-limit handling with retry logic
Audit logging for all tool executions
Never exposes tokens or secrets in responses

License

MIT