creatorloop

Why

There are plenty of "Instagram API for Claude" servers. creatorloop is built for the creator's loop instead:

• Learn from data, not vibes. Best and worst posts with their hooks, format comparison, follows per 1,000 reach, Reels watch time, best day and hour — and which captions (language, question hook, CTA, length) actually work.
• Spy on competitors legally. Track professional accounts, keep their follower history, and get alerted to the posts that did N× better than their median. Analyse any public post by URL, slides included.
• Make the content. A Remotion Reel template with automatic checks (first-second rule, safe zones, "not a copy of the carousel"), original music and licensed 3D objects.
• Publish safely. Two-step publishing with a preview, a queue with fingerprints (a changed file blocks the post), 24 h / 72 h post reviews and comment replies — every public action needs your explicit OK.
• Official API only. No scraping, no browser automation, no risk to your account.

Quick start

You need uv, Claude Desktop, an Instagram Business or Creator account linked to a Facebook Page, and your own Meta app (5-minute guide).

uvx --from creatorloop creatorloop-setup

It connects Claude Desktop and opens a setup page in your browser: enter your app's App ID and App Secret, press Continue with Facebook, done. Then ask Claude: "How did my last 10 posts do, and what should I post next?"

Already in Claude? Ask "connect my Instagram": Claude opens the same page (open_setup). Your App Secret and token are typed only into that local page, never into the chat.

creatorloop-setup finds the Claude Desktop config on Windows (including the Microsoft Store build), macOS and Linux, keeps your other servers, makes a backup and creates your settings file. Claude Desktop rewrites its config while it runs, so on macOS the command quits and reopens it for you; on Windows and Linux it asks you to quit it first.

One-click install (Claude Desktop)

Prefer not to open a terminal? Download the .mcpb file from the latest release and double-click it (or drag it into Claude Desktop → Settings → Extensions). Claude Desktop sets up Python and the dependencies itself, so the first start takes a minute. Leave the two optional fields empty and ask Claude "connect my Instagram": the same setup page opens. Fill them in only if you already have a token and account ID — values entered there win over the setup page. If Claude Desktop says it can't find uv, install it (see Installing uv above) and restart Claude Desktop.

docker build -t creatorloop https://github.com/pandich93/creatorloop.gitmkdir "$HOME/creatorloop"

docker run --rm -it -p 127.0.0.1:8765:8765 -v "$HOME/creatorloop:/data" --entrypoint creatorloop-auth creatorloop \  login --no-browser --port 8765 --bind 0.0.0.0

{  "mcpServers": {    "creatorloop": {      "command": "docker",      "args": ["run", "-i", "--rm", "-v", "/Users/you/creatorloop:/data", "creatorloop"]    }  }}

What you can ask

• "Make a report on my content for the last 60 days. Reels or carousels — what works better, and when should I post?"
• "Compare me with @competitor1 and @competitor2. Who has the higher engagement and why?"
• "Analyse this post https://www.instagram.com/p/… and write my own version of it."
• "Track @competitor and tell me every week which of their posts took off."
• "Check the hashtags #ai, #productivity and #startup. Check the quota first."
• "Queue the post from folder my-first-reel for the next free slot." → preview → "yes" → it goes out on time.
• "Which new comments haven't I answered? Draft replies." → you approve each reply.

Ready-made prompts in Claude Desktop's + menu: Weekly Instagram report, Competitor brief, Data-driven content ideas.

Tools

34 tools in total. Tools that change something on Instagram are annotated as such for Claude, and their descriptions tell it to act only after you approve: publish_media and reply_comment after you OK the preview or the exact text, queue_post only with confirm=true after you saw the preview.

Publishing

Put the files into a folder inside your content folder (<creatorloop home>/content/<name>/):

my-carousel/                   my-reel/  slide_01.png … slide_10.png    reel.mp4        # H.264/HEVC, 23–60 fps, ≤1920 px wide, 3 s–15 min, ≤300 MB  caption.txt                    caption.txt                                 reel.json       # optional: {"cover_ms": 1667, "share_to_feed": true, "trial": "SS_PERFORMANCE"}

• Slides: 1–10 PNG/JPG (API limit), aspect ratio 4:5 to 1.91:1, ordered by file name. Everything below a --- line in caption.txt is notes and is not published.
• Then: "prepare the post from folder my-carousel" → preview → "publish". Or queue it for a slot.
• Carousels: Instagram downloads images from a public URL, so creatorloop opens a temporary Cloudflare Quick Tunnel for that minute. Install cloudflared once: winget install --id Cloudflare.cloudflared -e (Windows), brew install cloudflared (macOS) or a package from pkg.cloudflare.com (Linux).
• Reels upload directly to Meta (no tunnel). The MP4 header is checked before upload (duration, size, width, moov first) with the exact ffmpeg fix if something is off.
• Queue slots default to Tue/Thu/Sun 19:00 in your timezone — an example, change QUEUE_SLOTS in the settings file. A queued post is blocked if its files or caption change after you approved it, and is marked missed if your computer was asleep for more than 3 hours past the slot.
• Meta's limit is 100 posts per rolling 24 hours; list_publications shows what is left. Publishing is never retried automatically, so there are no duplicates.

Making the content itself: see examples/ and the content pipeline — a sample carousel, a sample Reel storyboard and the Remotion Reel template.

What the Instagram API allows (and doesn't)

Engagement rate for your posts = Σ(likes + comments + saves + shares) / Σreach × 100 (weighted, so tiny posts don't skew it). Posts younger than 72 h are reported separately as "still growing". Competitors' ER is per follower — the API does not expose their reach.

Settings

creatorloop-setup creates .env in your creatorloop home folder:

Set CREATORLOOP_HOME to use another folder. The home folder holds .env, the creatorloop.db database and the content/ folder.

The token expiry shows up in get_api_status, and every tool answer carries a token_warning 14 days before expiry.

FAQ

Data & privacy

• Your token, settings, database and content stay on your computer in the creatorloop home folder.
• creatorloop talks to Meta only: the Instagram Graph API (graph.facebook.com, rupload.facebook.com for video uploads) and Instagram's media servers when it downloads the slides of a post you asked it to analyse.
• To publish carousels (and Reels, if the direct upload is refused) it opens a temporary Cloudflare Quick Tunnel to your local files for the minute Meta needs to fetch them, then closes it and deletes the temporary copies.
• No analytics, telemetry or third-party services.

Development

git clone https://github.com/pandich93/creatorloop && cd creatorloopuv syncuv run pytest            # offline: mocked Graph API and captured response shapesuv run creatorloop-setup # points Claude Desktop at this checkout instead of the PyPI package

See CONTRIBUTING.md. Security issues: SECURITY.md.

Disclaimer

creatorloop is an independent open-source project. Not affiliated with, endorsed or sponsored by Meta or Instagram. "Instagram" is a trademark of Meta Platforms, Inc. You are responsible for complying with the Meta Platform Terms and Instagram's policies when you use it.

License

MIT. The Reel template in examples/reel-template uses Remotion, which has its own licence; bundled assets and fonts are listed in examples/reel-template/public/assets/LICENSES.md.