creatorloop 0.1.0__tar.gz

creatorloop-0.1.0/.gitignore

@@ -0,0 +1,21 @@
+.env
+data/
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+*.egg-info/
+dist/
+.ruff_cache/
+.idea/
+node_modules/
+*.mp4
+!tests/fixtures/*.mp4
+*.mov
+*.webm
+*.wav
+*.mp3
+examples/**/*.png
+examples/**/*.jpg
+examples/**/out/
+examples/**/slides/

creatorloop-0.1.0/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-13
+
+First public release.
+
+### Added
+- MCP server with 33 tools for one Instagram professional account via the official Instagram Graph API v26.0:
+  own analytics and content reports, caption insights, audience demographics, competitor analysis and tracking
+  (Business Discovery), viral-post detection, post analysis by URL, hashtag research with a 30-per-week quota guard.
+- Two-step publishing of carousels and Reels (resumable upload for Reels), a publishing queue with fingerprints,
+  24 h / 72 h post reviews, new-comment inbox and replies.
+- `creatorloop-setup`: connects Claude Desktop on Windows (incl. Microsoft Store), macOS and Linux; quits and reopens
+  Claude Desktop on macOS so it does not overwrite the config.
+- `creatorloop-auth`: token exchange, account ID lookup, token check.
+- Per-user home folder (`CREATORLOOP_HOME`) for settings, database and content; system timezone by default.
+- Three MCP prompts: weekly report, competitor brief, data-driven content ideas.
+- `examples/`: a sample carousel, a sample Reel storyboard and a Remotion Reel template with automatic checks.
+
+[Unreleased]: https://github.com/pandich93/creatorloop/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/pandich93/creatorloop/releases/tag/v0.1.0

creatorloop-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pandich
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

creatorloop-0.1.0/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.5
+Name: creatorloop
+Version: 0.1.0
+Summary: Open-source AI content studio for Instagram creators: Claude analyses what works, helps make Reels and carousels, schedules and reviews them via the official Instagram API
+Project-URL: Homepage, https://github.com/pandich93/creatorloop
+Project-URL: Repository, https://github.com/pandich93/creatorloop
+Project-URL: Issues, https://github.com/pandich93/creatorloop/issues
+Project-URL: Changelog, https://github.com/pandich93/creatorloop/blob/main/CHANGELOG.md
+Author: pandich
+License-Expression: MIT
+License-File: LICENSE
+Keywords: analytics,claude,content-creator,instagram,mcp,model-context-protocol,reels,social-media
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Multimedia :: Video
+Requires-Python: >=3.14
+Requires-Dist: httpx>=0.28
+Requires-Dist: mcp<3,>=2.3
+Requires-Dist: pillow>=11.3
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: tzdata>=2025.2
+Description-Content-Type: text/markdown
+
+<!-- mcp-name: io.github.pandich93/creatorloop -->
+<div align="center">
+
+# 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.
+
+[![CI](https://github.com/pandich93/creatorloop/actions/workflows/ci.yml/badge.svg)](https://github.com/pandich93/creatorloop/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/creatorloop.svg)](https://pypi.org/project/creatorloop/)
+[![Python](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[Русский](https://github.com/pandich93/creatorloop/blob/main/README.ru.md) · [Oʻzbekcha](https://github.com/pandich93/creatorloop/blob/main/README.uz.md)
+
+![creatorloop demo](https://raw.githubusercontent.com/pandich93/creatorloop/main/docs/media/demo.gif)
+
+</div>
+
+## 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](https://docs.astral.sh/uv/getting-started/installation/), [Claude Desktop](https://claude.ai/download),
+an Instagram **Business or Creator** account linked to a **Facebook Page**, and your own Meta app
+([5-minute guide](https://github.com/pandich93/creatorloop/blob/main/docs/meta-setup.md)).
+
+```bash
+uvx --from creatorloop creatorloop-setup        # 1. connect to Claude Desktop, create the settings file
+```
+
+2. Put your app's `META_APP_ID` and `META_APP_SECRET` into the settings file the command printed.
+3. Save a 60-day token and find your account ID (the short-lived token comes from Graph API Explorer, see the guide):
+
+```bash
+uvx --from creatorloop creatorloop-auth exchange --short-token <TOKEN> --write
+uvx --from creatorloop creatorloop-auth whoami --write
+uvx --from creatorloop creatorloop-auth check   # → OK: @your_account followers=...
+```
+
+Restart Claude Desktop and ask: *"How did my last 10 posts do, and what should I post next?"*
+
+<details>
+<summary>Installing uv</summary>
+
+| System | Command |
+|---|---|
+| Windows | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
+| macOS | `brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Linux | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+
+uv downloads Python 3.14 by itself if you don't have it.
+</details>
+
+`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.
+
+## 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
+
+| Area | Tools |
+|---|---|
+| Your account | `get_my_profile`, `get_my_media`, `get_media_insights`, `get_account_insights`, `get_audience_demographics` |
+| Content analysis | `get_my_content_report`, `get_caption_insights`, `get_post_history`, `post_reviews` |
+| Competitors | `get_competitor`, `compare_accounts`, `get_follower_history`, `track_competitor`, `untrack_competitor`, `list_tracked_competitors`, `update_tracked_competitors`, `find_viral_posts`, `get_competitor_post` |
+| Hashtags | `search_hashtag`, `compare_hashtags`, `plan_hashtag_research` |
+| Publishing | `prepare_post`, `get_post_job`, `publish_media`, `list_publications` |
+| Queue | `queue_post`, `list_queue`, `cancel_queued` |
+| Comments | `get_new_comments`, `reply_comment` |
+| Service | `get_api_status`, `clear_cache`, `restart_server` |
+
+33 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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
+  for that minute. Install `cloudflared` once: `winget install --id Cloudflare.cloudflared -e` (Windows),
+  `brew install cloudflared` (macOS) or a package from [pkg.cloudflare.com](https://pkg.cloudflare.com/index.html) (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/`](https://github.com/pandich93/creatorloop/blob/main/examples) and the [content pipeline](https://github.com/pandich93/creatorloop/blob/main/docs/content-pipeline.md) —
+a sample carousel, a sample Reel storyboard and the Remotion Reel template.
+
+## What the Instagram API allows (and doesn't)
+
+| | Possible | Not possible |
+|---|---|---|
+| **Your account** | Reach, views, likes, comments, saves, shares, profile visits, follows per post, Reels average watch time, audience demographics, account totals | Data older than 2 years; insights per carousel slide; Stories after 24 h |
+| **Competitors** (Business Discovery) | Public data of Business/Creator accounts: followers, posts, bio, likes, comments, Reels views per post | Personal or private accounts; their reach, saves, shares, demographics; Stories |
+| **Hashtags** | Top posts and posts from the last 24 h | More than **30 unique hashtags per rolling 7 days**; post authors; keyword, audio or trend search |
+| **Follower growth** | creatorloop saves a daily snapshot for you and every competitor you look at | History before the first snapshot |
+
+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:
+
+| System | Home folder |
+|---|---|
+| Windows | `%APPDATA%\creatorloop` |
+| macOS | `~/Library/Application Support/creatorloop` |
+| Linux | `~/.local/share/creatorloop` (or `$XDG_DATA_HOME/creatorloop`) |
+
+Set `CREATORLOOP_HOME` to use another folder. The home folder holds `.env`, the `creatorloop.db` database and the
+`content/` folder.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `IG_ACCESS_TOKEN` | yes | Long-lived (60 days) or System User (never expires) token — see [Meta setup](https://github.com/pandich93/creatorloop/blob/main/docs/meta-setup.md) |
+| `IG_USER_ID` | yes | Your Instagram professional account ID (`1784…`), not the username |
+| `GRAPH_API_VERSION` | no | Default `v26.0` |
+| `META_APP_ID`, `META_APP_SECRET` | no | Only for `creatorloop-auth exchange` |
+| `IG_TIMEZONE` | no | IANA name, e.g. `Europe/Berlin`. Default: your computer's timezone |
+| `QUEUE_SLOTS` | no | e.g. `Mon,Wed,Fri 20:00` |
+| `IG_DB_PATH`, `CACHE_TTL_*_MIN` | no | Database location, cache lifetime in minutes |
+
+The token expiry shows up in `get_api_status`, and every tool answer carries a `token_warning` 14 days before expiry.
+
+## FAQ
+
+<details><summary>Does it work with a personal Instagram account?</summary>
+No. Meta's API only serves Business and Creator accounts linked to a Facebook Page. Switching is free:
+Instagram → Settings → Account type and tools.
+</details>
+
+<details><summary>Do I need Meta App Review?</summary>
+Not for your own account: keep the app in Development mode, you are its admin. Hashtag search may require the
+"Instagram Public Content Access" feature for some accounts — creatorloop tells you if Meta refuses it.
+</details>
+
+<details><summary>Can it get my account banned?</summary>
+creatorloop uses only the official Graph API with your own app and token, within Meta's rate limits. It does no
+scraping and no browser automation.
+</details>
+
+<details><summary>Which AI clients does it work with?</summary>
+It is a standard MCP server (stdio). It is developed and tested with Claude Desktop; other MCP clients that support
+stdio servers should work too.
+</details>
+
+<details><summary>A metric is missing in the answer.</summary>
+Meta regularly removes metrics (e.g. `impressions` and `plays` in April 2025, replaced by `views`). creatorloop
+moves a refused metric to `unavailable` instead of failing and stops asking for it for 7 days. Insights can lag up to 48 h.
+</details>
+
+## 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
+
+```bash
+git clone https://github.com/pandich93/creatorloop && cd creatorloop
+uv sync
+uv run pytest            # offline: mocked Graph API and captured response shapes
+uv run creatorloop-setup # points Claude Desktop at this checkout instead of the PyPI package
+```
+
+See [CONTRIBUTING.md](https://github.com/pandich93/creatorloop/blob/main/CONTRIBUTING.md). Security issues: [SECURITY.md](https://github.com/pandich93/creatorloop/blob/main/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](https://developers.facebook.com/terms/) and Instagram's policies when you use it.
+
+## License
+
+[MIT](https://github.com/pandich93/creatorloop/blob/main/LICENSE). The Reel template in `examples/reel-template` uses [Remotion](https://www.remotion.dev), which has
+its own licence; bundled assets and fonts are listed in
+[`examples/reel-template/public/assets/LICENSES.md`](https://github.com/pandich93/creatorloop/blob/main/examples/reel-template/public/assets/LICENSES.md).

creatorloop-0.1.0/README.md

@@ -0,0 +1,225 @@
+<!-- mcp-name: io.github.pandich93/creatorloop -->
+<div align="center">
+
+# 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.
+
+[![CI](https://github.com/pandich93/creatorloop/actions/workflows/ci.yml/badge.svg)](https://github.com/pandich93/creatorloop/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/creatorloop.svg)](https://pypi.org/project/creatorloop/)
+[![Python](https://img.shields.io/badge/python-3.14-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+[Русский](https://github.com/pandich93/creatorloop/blob/main/README.ru.md) · [Oʻzbekcha](https://github.com/pandich93/creatorloop/blob/main/README.uz.md)
+
+![creatorloop demo](https://raw.githubusercontent.com/pandich93/creatorloop/main/docs/media/demo.gif)
+
+</div>
+
+## 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](https://docs.astral.sh/uv/getting-started/installation/), [Claude Desktop](https://claude.ai/download),
+an Instagram **Business or Creator** account linked to a **Facebook Page**, and your own Meta app
+([5-minute guide](https://github.com/pandich93/creatorloop/blob/main/docs/meta-setup.md)).
+
+```bash
+uvx --from creatorloop creatorloop-setup        # 1. connect to Claude Desktop, create the settings file
+```
+
+2. Put your app's `META_APP_ID` and `META_APP_SECRET` into the settings file the command printed.
+3. Save a 60-day token and find your account ID (the short-lived token comes from Graph API Explorer, see the guide):
+
+```bash
+uvx --from creatorloop creatorloop-auth exchange --short-token <TOKEN> --write
+uvx --from creatorloop creatorloop-auth whoami --write
+uvx --from creatorloop creatorloop-auth check   # → OK: @your_account followers=...
+```
+
+Restart Claude Desktop and ask: *"How did my last 10 posts do, and what should I post next?"*
+
+<details>
+<summary>Installing uv</summary>
+
+| System | Command |
+|---|---|
+| Windows | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
+| macOS | `brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+| Linux | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
+
+uv downloads Python 3.14 by itself if you don't have it.
+</details>
+
+`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.
+
+## 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
+
+| Area | Tools |
+|---|---|
+| Your account | `get_my_profile`, `get_my_media`, `get_media_insights`, `get_account_insights`, `get_audience_demographics` |
+| Content analysis | `get_my_content_report`, `get_caption_insights`, `get_post_history`, `post_reviews` |
+| Competitors | `get_competitor`, `compare_accounts`, `get_follower_history`, `track_competitor`, `untrack_competitor`, `list_tracked_competitors`, `update_tracked_competitors`, `find_viral_posts`, `get_competitor_post` |
+| Hashtags | `search_hashtag`, `compare_hashtags`, `plan_hashtag_research` |
+| Publishing | `prepare_post`, `get_post_job`, `publish_media`, `list_publications` |
+| Queue | `queue_post`, `list_queue`, `cancel_queued` |
+| Comments | `get_new_comments`, `reply_comment` |
+| Service | `get_api_status`, `clear_cache`, `restart_server` |
+
+33 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](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
+  for that minute. Install `cloudflared` once: `winget install --id Cloudflare.cloudflared -e` (Windows),
+  `brew install cloudflared` (macOS) or a package from [pkg.cloudflare.com](https://pkg.cloudflare.com/index.html) (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/`](https://github.com/pandich93/creatorloop/blob/main/examples) and the [content pipeline](https://github.com/pandich93/creatorloop/blob/main/docs/content-pipeline.md) —
+a sample carousel, a sample Reel storyboard and the Remotion Reel template.
+
+## What the Instagram API allows (and doesn't)
+
+| | Possible | Not possible |
+|---|---|---|
+| **Your account** | Reach, views, likes, comments, saves, shares, profile visits, follows per post, Reels average watch time, audience demographics, account totals | Data older than 2 years; insights per carousel slide; Stories after 24 h |
+| **Competitors** (Business Discovery) | Public data of Business/Creator accounts: followers, posts, bio, likes, comments, Reels views per post | Personal or private accounts; their reach, saves, shares, demographics; Stories |
+| **Hashtags** | Top posts and posts from the last 24 h | More than **30 unique hashtags per rolling 7 days**; post authors; keyword, audio or trend search |
+| **Follower growth** | creatorloop saves a daily snapshot for you and every competitor you look at | History before the first snapshot |
+
+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:
+
+| System | Home folder |
+|---|---|
+| Windows | `%APPDATA%\creatorloop` |
+| macOS | `~/Library/Application Support/creatorloop` |
+| Linux | `~/.local/share/creatorloop` (or `$XDG_DATA_HOME/creatorloop`) |
+
+Set `CREATORLOOP_HOME` to use another folder. The home folder holds `.env`, the `creatorloop.db` database and the
+`content/` folder.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `IG_ACCESS_TOKEN` | yes | Long-lived (60 days) or System User (never expires) token — see [Meta setup](https://github.com/pandich93/creatorloop/blob/main/docs/meta-setup.md) |
+| `IG_USER_ID` | yes | Your Instagram professional account ID (`1784…`), not the username |
+| `GRAPH_API_VERSION` | no | Default `v26.0` |
+| `META_APP_ID`, `META_APP_SECRET` | no | Only for `creatorloop-auth exchange` |
+| `IG_TIMEZONE` | no | IANA name, e.g. `Europe/Berlin`. Default: your computer's timezone |
+| `QUEUE_SLOTS` | no | e.g. `Mon,Wed,Fri 20:00` |
+| `IG_DB_PATH`, `CACHE_TTL_*_MIN` | no | Database location, cache lifetime in minutes |
+
+The token expiry shows up in `get_api_status`, and every tool answer carries a `token_warning` 14 days before expiry.
+
+## FAQ
+
+<details><summary>Does it work with a personal Instagram account?</summary>
+No. Meta's API only serves Business and Creator accounts linked to a Facebook Page. Switching is free:
+Instagram → Settings → Account type and tools.
+</details>
+
+<details><summary>Do I need Meta App Review?</summary>
+Not for your own account: keep the app in Development mode, you are its admin. Hashtag search may require the
+"Instagram Public Content Access" feature for some accounts — creatorloop tells you if Meta refuses it.
+</details>
+
+<details><summary>Can it get my account banned?</summary>
+creatorloop uses only the official Graph API with your own app and token, within Meta's rate limits. It does no
+scraping and no browser automation.
+</details>
+
+<details><summary>Which AI clients does it work with?</summary>
+It is a standard MCP server (stdio). It is developed and tested with Claude Desktop; other MCP clients that support
+stdio servers should work too.
+</details>
+
+<details><summary>A metric is missing in the answer.</summary>
+Meta regularly removes metrics (e.g. `impressions` and `plays` in April 2025, replaced by `views`). creatorloop
+moves a refused metric to `unavailable` instead of failing and stops asking for it for 7 days. Insights can lag up to 48 h.
+</details>
+
+## 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
+
+```bash
+git clone https://github.com/pandich93/creatorloop && cd creatorloop
+uv sync
+uv run pytest            # offline: mocked Graph API and captured response shapes
+uv run creatorloop-setup # points Claude Desktop at this checkout instead of the PyPI package
+```
+
+See [CONTRIBUTING.md](https://github.com/pandich93/creatorloop/blob/main/CONTRIBUTING.md). Security issues: [SECURITY.md](https://github.com/pandich93/creatorloop/blob/main/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](https://developers.facebook.com/terms/) and Instagram's policies when you use it.
+
+## License
+
+[MIT](https://github.com/pandich93/creatorloop/blob/main/LICENSE). The Reel template in `examples/reel-template` uses [Remotion](https://www.remotion.dev), which has
+its own licence; bundled assets and fonts are listed in
+[`examples/reel-template/public/assets/LICENSES.md`](https://github.com/pandich93/creatorloop/blob/main/examples/reel-template/public/assets/LICENSES.md).

creatorloop-0.1.0/README.ru.md

@@ -0,0 +1,34 @@
+# creatorloop
+
+**Открытая AI-студия контента для авторов в Instagram на базе Claude и официального Instagram API.**
+
+Анализ того, что работает → создание Reels и каруселей → публикация или очередь → разбор результатов через 24 и 72 часа.
+Всё — в чате с Claude.
+
+- **Данные вместо догадок:** лучшие и худшие посты с хуками, сравнение форматов, подписки на 1000 охвата,
+  время просмотра Reels, лучшие день и час, какие подписи работают.
+- **Конкуренты легально:** отслеживание, история подписчиков, посты, которые набрали в N раз больше медианы,
+  разбор любого публичного поста по ссылке.
+- **Создание контента:** шаблон Reels на Remotion с автопроверками, своя музыка, 3D-объекты с лицензиями.
+- **Безопасная публикация:** превью перед каждой публикацией, очередь с защитой от изменённых файлов,
+  отчёты через 24/72 часа, ответы на комментарии только после вашего «да».
+- **Только официальный API:** без скрейпинга и риска для аккаунта.
+
+## Быстрый старт
+
+Нужны [uv](https://docs.astral.sh/uv/getting-started/installation/), Claude Desktop, аккаунт Instagram типа
+**Business** или **Creator**, привязанная **Facebook-страница** и своё приложение Meta
+([гайд, на английском](docs/meta-setup.md)).
+
+```bash
+uvx --from creatorloop creatorloop-setup
+uvx --from creatorloop creatorloop-auth exchange --short-token <ТОКЕН> --write
+uvx --from creatorloop creatorloop-auth whoami --write
+```
+
+Перед второй командой впишите `META_APP_ID` и `META_APP_SECRET` в файл настроек, путь к которому покажет первая.
+Перезапустите Claude Desktop и спросите: *«Как зашли мои последние 10 постов и что мне публиковать дальше?»*
+
+Полная документация — в [README на английском](README.md).
+
+Независимый open source проект, не связан с Meta и Instagram. Лицензия [MIT](LICENSE).

creatorloop-0.1.0/README.uz.md

@@ -0,0 +1,34 @@
+# creatorloop
+
+**Instagram mualliflari uchun ochiq kodli AI kontent studiyasi: Claude va rasmiy Instagram API asosida.**
+
+Nima ishlayotganini tahlil qilish → Reels va karusellar yaratish → joylash yoki navbatga qoʻyish →
+24 va 72 soatdan keyin natijani koʻrib chiqish. Hammasi Claude bilan suhbatda.
+
+- **Taxmin emas, raqamlar:** eng yaxshi va eng yomon postlar birinchi qatori (hook) bilan, formatlar taqqoslash, har 1000 qamrovga
+  obunachilar, Reels koʻrish vaqti, eng yaxshi kun va soat, qaysi izohlar (caption) ishlaydi.
+- **Raqobatchilar — qonuniy:** kuzatish, obunachilar tarixi, akkaunt medianasidan N barobar koʻp yigʻgan postlar,
+  istalgan ochiq postni havola orqali tahlil qilish.
+- **Kontent yaratish:** Remotion asosidagi Reels shabloni, avtomatik tekshiruvlar, oʻz musiqasi, litsenziyali 3D obyektlar.
+- **Xavfsiz joylash:** har bir postdan oldin koʻrib chiqish (preview), oʻzgargan fayllardan himoyalangan navbat,
+  24/72 soatlik hisobotlar, izohlarga javob — faqat sizning roziligingizdan keyin.
+- **Faqat rasmiy API:** skreyping yoʻq, akkaunt uchun xavf yoʻq.
+
+## Tez boshlash
+
+Kerak boʻladi: [uv](https://docs.astral.sh/uv/getting-started/installation/), Claude Desktop, **Business** yoki
+**Creator** turidagi Instagram akkaunt, unga ulangan **Facebook sahifa** va oʻzingizning Meta ilovangiz
+([qoʻllanma, ingliz tilida](docs/meta-setup.md)).
+
+```bash
+uvx --from creatorloop creatorloop-setup
+uvx --from creatorloop creatorloop-auth exchange --short-token <TOKEN> --write
+uvx --from creatorloop creatorloop-auth whoami --write
+```
+
+Ikkinchi buyruqdan oldin birinchi buyruq koʻrsatgan sozlamalar fayliga `META_APP_ID` va `META_APP_SECRET` ni yozing.
+Claude Desktop'ni qayta ishga tushiring va soʻrang: *«Oxirgi 10 ta postim qanday ketdi va keyin nima joylashim kerak?»*
+
+Toʻliq hujjatlar — [ingliz tilidagi README](README.md)da.
+
+Mustaqil ochiq kodli loyiha, Meta va Instagram bilan bogʻliq emas. Litsenziya: [MIT](LICENSE).