Instagram Research

Research public Instagram Reels from a local dashboard, your terminal, or an MCP-compatible coding agent. Built by Automate Scale. MIT licensed.

The dashboard, CLI, and 22 MCP tools share the same jobs, evidence, and saved reports. Automatic analysis uses your selected local Codex or Claude Code profile. Instagram sign-in stays in a dedicated browser on your computer.

Install with your coding agent

Copy this into Codex, Claude Code, or another coding agent:

Install https://github.com/AutomateScaleAgency/instagram-research on my computer. Read AGENTS.md and docs/AGENT-INSTALL.md. Use the source beta installation, detect my available agents, and let me choose Codex, Claude Code, or both. Start the dashboard and connect my selected MCP clients. Let me sign into Instagram myself.

This is a source beta. Installation builds the Docker image locally; a downloadable prebuilt release is not published yet. The managed installer requires a separately verified release manifest. The working source installation is below.

Related MCP server: instagram-mcp

Start locally

Prerequisites: Git, Node.js 24+, npm 11, and Docker with Compose running. Install and sign into Codex or Claude Code if you want automatic analysis. The first Docker build downloads browser and media dependencies.

git clone https://github.com/AutomateScaleAgency/instagram-research.git
cd instagram-research
npm ci --ignore-scripts
./bin/ig-research up

1. Open http://127.0.0.1:3100.

2. Open Instagram login from the dashboard and sign in yourself.

3. Return to the dashboard and choose Finish login.

4. Choose an available provider and model, then discover a public profile.

5. Review the profile, Reel limit, evidence, and report-saving confirmation before starting research.

Stop with ./bin/ig-research down; saved data is preserved. Keep this checkout at its installed path because source MCP registrations refer to it.

Connect your agent

Start the service first. Configure a stdio MCP server using the absolute path on your computer:

{
  "command": "/absolute/path/to/instagram-research/bin/ig-research",
  "args": ["mcp"]
}

Codex app and CLI share their Codex MCP configuration. Claude Code and other clients use their own registration. See agent installation and the 22-tool MCP reference. MCP access and a dashboard analysis provider are separate connections; verify both.

For terminal commands, run ./bin/ig-research help or read the CLI reference.

Beta verification and limits

The candidate underlying this beta passed 263 offline tests, dashboard browser fixtures, and a temporary macOS Apple Silicon installation with Chromium and real SDK MCP checks. One authorized live dashboard workflow using Codex processed two Reels, saved a cited report, and returned the same report through CLI and MCP.

Live Claude analysis and complete named-client acceptance remain unverified. Linux and Windows/WSL2 have synthetic platform checks, not full installed-product certification. Windows execution is designed for one WSL2 distribution with Docker Desktop; native Windows research is outside this beta. See platform acceptance.

Research only public targets you are authorized to collect. Login challenges and rate limits stop collection. Credentials remain operator-controlled, and source content is treated as untrusted evidence. See security and dependency status.

Development

Install Python 3, ShellCheck, and FFmpeg alongside Node and Docker. Run npm ci --ignore-scripts and npm run check. CI uses synthetic fixtures without Instagram or provider credentials.

Architecture · Installation · Troubleshooting · Contributing · Release checklist · MIT license