instagram-use

Make Instagram usable for AI agents.
Standardized Meta Graph API v21.0 Twin architecture, Model Context Protocol (MCP) server, and Agent plugin for autonomous Instagram workflows via session cookies or anonymous Ghost Mode.

Overview

Modern AI agents need hands and eyes on social platforms, but integrating with Instagram has traditionally forced teams into one of two dead ends:

1. The Official Meta App Wall: Requires burdensome corporate business verification, multi-week app reviews, and severely restricted permission scopes.

2. Fragile Web Scrapers: Unstructured HTML parsing that breaks with every frontend release and triggers instant security checkpoints or account bans.

instagram-use bridges this gap. It models public actions and authenticated workflows 1:1 after the official Meta Graph API v21.0 specifications, executing them directly through clean GraphQL and private session transports.

Designed specifically for LLM tool-calling (Hermes, Claude Desktop/MCP, Antigravity, LangChain, CrewAI, AutoGen), instagram-use outputs strictly typed, structured JSON payloads with built-in safety circuit breakers.

Related MCP server: @inssist/mcp

Dual Operational Modes

instagram-use operates in two distinct modes depending on task requirements:

┌────────────────────────────────────────────────────────┐
│                     instagram-use                      │
├───────────────────────────┬────────────────────────────┤
│        Ghost Mode         │     Authenticated Mode     │
│   (Zero Login / Public)   │   (Cookie Session / Auth)  │
├───────────────────────────┼────────────────────────────┤
│ • Profile Inspection      │ • Story Publishing         │
│ • Public Post / Reel Data │ • Feed Post Publishing     │
│ • Public Comment Harvest  │ • Direct Message (Send/DM) │
│ • Hashtag / User Search   │ • Direct Inbox Inspection  │
│ • Competitor Account Audit│ • Post / Reel Commenting   │
│                           │ • 30-Day Account Insights  │
└───────────────────────────┴────────────────────────────┘

1. Ghost Mode (Zero Footprint / No Login)

• Zero Credentials Required: No account, password, or cookies necessary.

• Risk-Free Exploration: Inspect competitor profiles, harvest public comment threads, scan viral reels, and search hashtags without leaving an audit trail or risking primary accounts.

• Ideal For: Market intelligence agents, competitor monitoring, sentiment scrapers, and trend discovery bots.

2. Authenticated Mode (Session-Based Digital Twin)

• Cookie-Based Authentication: Operates through a standard desktop session file (instagram_session.json containing sessionid and csrftoken). No plaintext passwords ever stored or requested.

• Full Action Surface: Publish stories and feed posts, respond to direct messages, post comments, and extract 30-day professional account analytics.

• Anti-Ban Protection: Enforces single-attempt fail-closed circuit breakers and strict string deduplication limits to protect account health.

Provided Tools Reference

instagram-use exposes 12 deterministic tools for LLM tool calling:

Installation & Setup

Requirements

• Python >= 3.10

• Node.js >= 18.0.0

• twingraph engine CLI (globally available in PATH)

Option A: Install as a Hermes Agent Plugin

hermes plugins install instagram-use

Or clone directly into your Hermes plugins directory:

git clone https://github.com/dalroot/instagram-use.git ~/.hermes/plugins/instagram-use

Option B: Use as an MCP Server (Model Context Protocol)

Add instagram-use to your MCP configuration (Claude Desktop, Cursor, Antigravity, etc.):

{
  "mcpServers": {
    "instagram": {
      "command": "twingraph",
      "args": ["mcp"],
      "env": {
        "INSTAGRAM_SESSION_PATH": "/path/to/instagram_session.json"
      }
    }
  }
}

Option C: Standalone Python / CLI Integration

Clone and install dependencies:

git clone https://github.com/dalroot/instagram-use.git
cd instagram-use
pip install -e .

Authentication & Session Setup

For Ghost Mode, no authentication is required.

For Authenticated Mode:

1. Run the interactive session generator:

   twingraph login

   This opens a secure browser window for you to log in to Instagram once.

2. The session is automatically persisted to ~/instagram_session.json.

3. Alternatively, you can supply your existing cookies manually:

   {
     "cookies": {
       "sessionid": "YOUR_SESSION_ID",
       "ds_user_id": "YOUR_USER_ID",
       "csrftoken": "YOUR_CSRF_TOKEN"
     }
   }

Safety & Circuit Breaker Architecture

Automated agents can trigger platform checkpoints if they get stuck in loops or send repetitive payloads. instagram-use includes built-in protective layers:

• Single-Attempt Fail-Closed: If an authenticated request encounters a non-200 response or security challenge, the circuit breaker immediately trips and halts execution. Automated retry loops are strictly blocked.

• String Deduplication Caps: Dispatches of identical comments or messages are capped at safe thresholds to prevent triggering automated spam classifiers.

• Strict Parameter Coercion: URLs, shortcodes, and usernames are automatically validated and resolved before executing network requests.

Example Agent Prompts

# Publishing a Story
Agent Prompt: "Publish the graphic at /tmp/announcement.jpg as an Instagram story."
Tool Called: instagram_publish_story(image_input="/tmp/announcement.jpg")

# Direct Message Inquiries
Agent Prompt: "Check our direct message inbox for any unread customer questions and summarize them."
Tool Called: instagram_get_inbox(limit=10)

# Anonymous Competitor Audit (Ghost Mode)
Agent Prompt: "Inspect the public profile @competitor_brand, calculate their average reel engagement, and summarize their top 3 recent posts."
Tools Called: 
1. instagram_get_profile(username="competitor_brand")
2. instagram_get_posts(username="competitor_brand", count=10)

Repository Metadata & Topics

Recommended configuration for the GitHub repository:

• Repository Name: instagram-use

• Short Description (About):
  Make Instagram usable for AI agents. Meta Graph API v21.0 Twin architecture, MCP server, and Agent plugin for stories, posts, DMs, comments, and anonymous Ghost Mode.

• Website: https://github.com/dalroot/instagram-use

• GitHub Topics:
  instagram-use, ai-agents, mcp-server, llm-tools, instagram-agent, agent-toolkit, hermes-agent, meta-graph-api, cookie-session, automation

License

This project is licensed under the MIT License. See LICENSE for details.