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:

1. User Request - Natural language input
2. Intent Detection - Determine required operation
3. Permission Check - Validate API access
4. Tool Selection - Map to appropriate MCP tool
5. Instagram API - Execute authorized API call
6. Data Validation - Validate response data
7. Analytics/Reasoning - Process and analyze results
8. 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