# Instagram Research

Research public Instagram Reels from a local dashboard, your terminal, or an MCP-compatible coding agent. Built by [Automate Scale](https://github.com/AutomateScaleAgency). MIT licensed.

The dashboard, CLI, and 48 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.

## Reports and content planning

Use Content studio to keep creator brands or agency clients separate, save a brand brief, build cited competitor reports, and turn recommendations into a four-week calendar. Plans retain their source versions, effort budgets, and draft/review status. Export report and calendar PDFs or Markdown; export calendars as CSV.

Coding agents can use the packaged `ig-competitor-analysis` and `ig-content-calendar` skills, or the same prepare/save operations directly through MCP. See [content planning](docs/CONTENT-PLANNING.md).

## 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.

## 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.

```sh
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:

```json
{
  "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](docs/AGENT-INSTALL.md) and the [MCP reference](docs/MCP.md). 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](docs/CLI.md).

## Beta verification and limits

The content-planning candidate passed 379/379 tests in its exact Linux/arm64 image and isolated macOS installation checks covering UI/CLI/MCP parity, exports, and update/rollback/data preservation. Independent review found no remaining consequential issues. Native Codex skill discovery and an isolated Codex MCP connection passed; native Claude skill discovery, desktop presentation, and live content-generation workflows remain unverified. These are synthetic acceptance results, not certification for every agent or platform.

The preceding research 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](docs/PLATFORM-ACCEPTANCE.md).

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](docs/SECURITY.md) and [dependency status](docs/DEPENDENCIES.md).

## Development

Install Python 3, ShellCheck, FFmpeg, and Poppler alongside Node and Docker. Run `npm ci --ignore-scripts`, `npx playwright install chromium`, and `npm run check`. On Linux, use `npx playwright install --with-deps chromium` to install the browser system dependencies. CI uses synthetic fixtures without Instagram or provider credentials.

[Architecture](docs/ARCHITECTURE.md) · [Installation](docs/INSTALL.md) · [Troubleshooting](docs/TROUBLESHOOTING.md) · [Contributing](docs/CONTRIBUTING.md) · [Release checklist](docs/PUBLIC-RELEASE-CHECKLIST.md) · [MIT license](LICENSE)