creatorloop

creatorloop

Open-source AI content studio for Instagram creators, built on Claude and the official Instagram API.

Analyse what works → make Reels and carousels → publish or queue them → review how they did. All from a chat with Claude.

Русский · Oʻzbekcha

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.

Installing uv

creatorloop runs on Python 3.12 or newer; uv downloads one by itself if you don't have it.

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.

Running in Docker instead of uv

Build the image straight from GitHub and keep your settings in a folder on your computer:

docker build -t creatorloop https://github.com/pandich93/creatorloop.git

mkdir "$HOME/creatorloop"

If you use the post queue, first create .env in that folder with IG_TIMEZONE=Europe/Berlin (your zone): the container runs in UTC.

Connect your account (the setup page runs in the container; open the printed link in your browser). Keep all three 8765 the same; to use another port change all three:

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

creatorloop-setup doesn't run inside Docker, so add the server to claude_desktop_config.json yourself, with the full path to the folder:

{

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

Post folders for prepare_post and queue_post go into creatorloop/content/. The image includes cloudflared for publishing carousels.

The open_setup tool does not work inside Docker; use the command above to reconnect.

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 ( /content/ /):

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_warn