Instagram HTTPX MCP Server

<p align="left"> <a href="https://pypi.org/project/instagram-httpx/" target="_blank"><img src="https://img.shields.io/pypi/v/instagram-httpx?color=blue" alt="PyPI Version"></a> <a href="https://github.com/ishan-parihar/instagram-httpx/actions/workflows/ci.yml" target="_blank"><img src="https://github.com/ishan-parihar/instagram-httpx/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI Status"></a> <a href="https://github.com/ishan-parihar/instagram-httpx/actions/workflows/release.yml" target="_blank"><img src="https://github.com/ishan-parihar/instagram-httpx/actions/workflows/release.yml/badge.svg?branch=main" alt="Release"></a> <a href="https://github.com/ishan-parihar/instagram-httpx/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/badge/License-Apache%202.0-%233fb950?labelColor=32383f" alt="License"></a> <img src="https://img.shields.io/badge/Python-3.12+-blue" alt="Python Version"> </p>

Model Context Protocol server that lets AI assistants interact with Instagram through intelligent automation.

Access profiles, posts, reels, Business/Creator insights, direct messages, and full-scope content creation with smart aspect ratio processing, modern Instagram specifications, multi-account management, and agent-optimized CLI interface.

Quick Install

One-line installation:

curl -fsSL https://raw.githubusercontent.com/ishan-parihar/instagram-httpx/main/install.sh | bash

What It Does

• Smart Content Processing: Automatic aspect ratio detection and conversion (4:5, 1:1, 1.91:1, 9:16) with letterbox/crop modes
• Modern Instagram Specs: Extended video durations (180s feed/reels, 60s stories) and latest format support
• Multi-Account Management: Switch between multiple Instagram accounts with posting limits and cooldowns
• Comment-Based DM Automation: Trigger system for automated responses to post comments
• Feed Browsing: Home feed, discover feed, and user timeline access
• Full Content Creation: Photos, videos, carousels, stories, and reels with location/tagging
• Agent-Optimized CLI: AXI-compliant interface with TOON output and session integrations
• Production Ready: Systemd persistence, error handling, and comprehensive validation

Quick Start

1. Install

curl -fsSL https://raw.githubusercontent.com/ishan-parihar/instagram-httpx/main/install.sh | bash

2. Configure your MCP client

Add to your client's MCP config:

{
  "mcpServers": {
    "instagram": {
      "command": "uvx",
      "args": ["instagram-httpx"]
    }
  }
}

3. First tool call

Restart your MCP client. On the first Instagram tool call, a login window opens if no session exists. Log in once, and cookies persist across restarts.

Smart Processing

The server automatically handles Instagram's complex media specifications:

• Auto Aspect Ratio Detection: Converts any media to the closest valid Instagram ratio
• Media-Type-Aware Processing: Uses letterbox for stories/reels (preserves content), crop for feed (clean aesthetic)
• Extended Duration Support: 180s for feed/reels, 60s for stories (vs old 60s/15s limits)
• Landscape Format Support: 1.91:1 cinematic format for feed posts
• Flexible Processing Modes: Auto, fit (letterbox), and crop (center crop) options

Example:

# Auto-detect best ratio and processing mode
result = await upload_photo(
    image_path="photo.jpg",
    caption="Smart processed",
    aspect_ratio="auto",  # Auto-detect closest valid ratio
    fit_mode="auto"       # Auto-select best processing mode
)

AI Agent Setup

AI coding agents in headless environments can authenticate by providing Instagram session cookies directly.

Option A: Set INSTAGRAM_COOKIES environment variable (recommended)

{
  "sessionid": "your_session_id_value",
  "csrftoken": "your_csrf_token_value"
}

Linux/macOS:

export INSTAGRAM_COOKIES='{"ses