creatorloop 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- creatorloop/__init__.py +13 -0
- creatorloop/__main__.py +3 -0
- creatorloop/analytics.py +577 -0
- creatorloop/auth_cli.py +133 -0
- creatorloop/comments.py +111 -0
- creatorloop/config.py +110 -0
- creatorloop/env.example +33 -0
- creatorloop/graph_client.py +224 -0
- creatorloop/instagram.py +461 -0
- creatorloop/paths.py +67 -0
- creatorloop/post_queue.py +196 -0
- creatorloop/publish.py +417 -0
- creatorloop/refs.py +188 -0
- creatorloop/reviews.py +116 -0
- creatorloop/server.py +816 -0
- creatorloop/setup_cli.py +175 -0
- creatorloop/storage.py +464 -0
- creatorloop/tunnel.py +169 -0
- creatorloop-0.1.0.dist-info/METADATA +254 -0
- creatorloop-0.1.0.dist-info/RECORD +23 -0
- creatorloop-0.1.0.dist-info/WHEEL +4 -0
- creatorloop-0.1.0.dist-info/entry_points.txt +4 -0
- creatorloop-0.1.0.dist-info/licenses/LICENSE +21 -0
creatorloop/tunnel.py
ADDED
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
"""Temporary public URL for local files: local HTTP server + Cloudflare Quick Tunnel.
|
|
2
|
+
|
|
3
|
+
Instagram's publishing API downloads media from a public URL. Instead of uploading slides to a
|
|
4
|
+
third-party host, we expose a temp folder for a minute via `cloudflared tunnel --url` (no account,
|
|
5
|
+
random *.trycloudflare.com host) and shut everything down right after Meta has fetched the files.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from __future__ import annotations
|
|
9
|
+
|
|
10
|
+
import asyncio
|
|
11
|
+
import contextlib
|
|
12
|
+
import functools
|
|
13
|
+
import glob
|
|
14
|
+
import logging
|
|
15
|
+
import os
|
|
16
|
+
import re
|
|
17
|
+
import shutil
|
|
18
|
+
import subprocess
|
|
19
|
+
import sys
|
|
20
|
+
import threading
|
|
21
|
+
from collections.abc import Mapping
|
|
22
|
+
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
|
|
23
|
+
from pathlib import Path
|
|
24
|
+
|
|
25
|
+
import httpx
|
|
26
|
+
|
|
27
|
+
log = logging.getLogger(__name__)
|
|
28
|
+
|
|
29
|
+
URL_RE = re.compile(r"https://[a-z0-9-]+\.trycloudflare\.com")
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class TunnelError(RuntimeError):
|
|
33
|
+
pass
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _fallback_candidates(platform: str, *, home: Path, env: Mapping[str, str]) -> list[Path]:
|
|
37
|
+
"""Usual install locations, for when PATH lacks them (Claude Desktop started from Dock / Start menu)."""
|
|
38
|
+
if platform == "win32":
|
|
39
|
+
local = env.get("LOCALAPPDATA", "")
|
|
40
|
+
winget_pkgs = Path(local) / "Microsoft" / "WinGet" / "Packages"
|
|
41
|
+
return [
|
|
42
|
+
Path(local) / "Microsoft" / "WinGet" / "Links" / "cloudflared.exe",
|
|
43
|
+
Path(env.get("ProgramFiles(x86)", r"C:\Program Files (x86)")) / "cloudflared" / "cloudflared.exe",
|
|
44
|
+
Path(env.get("ProgramFiles", r"C:\Program Files")) / "cloudflared" / "cloudflared.exe",
|
|
45
|
+
*(Path(p) for p in glob.glob(str(winget_pkgs / "Cloudflare.cloudflared*" / "*.exe"))),
|
|
46
|
+
]
|
|
47
|
+
dirs = ["/opt/homebrew/bin", "/usr/local/bin"] if platform == "darwin" else ["/usr/local/bin", "/usr/bin"]
|
|
48
|
+
return [*(Path(d) / "cloudflared" for d in dirs), home / ".local" / "bin" / "cloudflared"]
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def install_hint(platform: str = sys.platform) -> str:
|
|
52
|
+
if platform == "win32":
|
|
53
|
+
how = "`winget install --id Cloudflare.cloudflared -e`"
|
|
54
|
+
elif platform == "darwin":
|
|
55
|
+
how = "`brew install cloudflared`"
|
|
56
|
+
else:
|
|
57
|
+
how = "the package from https://pkg.cloudflare.com/index.html (or your distro's package manager)"
|
|
58
|
+
return f"cloudflared not found. Install it once: {how} (or set CLOUDFLARED_PATH in .env), then restart the server."
|
|
59
|
+
|
|
60
|
+
|
|
61
|
+
def find_cloudflared() -> str | None:
|
|
62
|
+
if env := os.getenv("CLOUDFLARED_PATH"):
|
|
63
|
+
return env if Path(env).exists() else None
|
|
64
|
+
if found := shutil.which("cloudflared"):
|
|
65
|
+
return found
|
|
66
|
+
for c in _fallback_candidates(sys.platform, home=Path.home(), env=os.environ):
|
|
67
|
+
if c.exists():
|
|
68
|
+
return str(c)
|
|
69
|
+
return None
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
class _QuietHandler(SimpleHTTPRequestHandler):
|
|
73
|
+
def log_message(self, format: str, *args) -> None: # noqa: A002 - stdlib signature
|
|
74
|
+
log.debug("tunnel http: " + format, *args)
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
class PublicTunnel:
|
|
78
|
+
"""async with PublicTunnel(folder) as base_url: ... -> files are at f"{base_url}/{name}"."""
|
|
79
|
+
|
|
80
|
+
def __init__(self, directory: Path, *, cloudflared: str | None = None, timeout: float = 45.0) -> None:
|
|
81
|
+
self.directory = directory
|
|
82
|
+
self.cloudflared = cloudflared or find_cloudflared()
|
|
83
|
+
self.timeout = timeout
|
|
84
|
+
self._server: ThreadingHTTPServer | None = None
|
|
85
|
+
self._proc: subprocess.Popen | None = None
|
|
86
|
+
self.url: str | None = None
|
|
87
|
+
self.locally_reachable = True
|
|
88
|
+
|
|
89
|
+
async def __aenter__(self) -> str:
|
|
90
|
+
return await self.start()
|
|
91
|
+
|
|
92
|
+
async def __aexit__(self, *exc) -> None:
|
|
93
|
+
await self.stop()
|
|
94
|
+
|
|
95
|
+
async def start(self) -> str:
|
|
96
|
+
if not self.cloudflared:
|
|
97
|
+
raise TunnelError(install_hint())
|
|
98
|
+
handler = functools.partial(_QuietHandler, directory=str(self.directory))
|
|
99
|
+
self._server = ThreadingHTTPServer(("127.0.0.1", 0), handler)
|
|
100
|
+
port = self._server.server_address[1]
|
|
101
|
+
threading.Thread(target=self._server.serve_forever, daemon=True).start()
|
|
102
|
+
|
|
103
|
+
# stdin/stdout must NOT be inherited: they are the MCP stdio channel
|
|
104
|
+
creationflags = getattr(subprocess, "CREATE_NO_WINDOW", 0)
|
|
105
|
+
self._proc = subprocess.Popen(
|
|
106
|
+
[self.cloudflared, "tunnel", "--no-autoupdate", "--url", f"http://127.0.0.1:{port}"],
|
|
107
|
+
stdin=subprocess.DEVNULL,
|
|
108
|
+
stdout=subprocess.DEVNULL,
|
|
109
|
+
stderr=subprocess.PIPE,
|
|
110
|
+
text=True,
|
|
111
|
+
encoding="utf-8",
|
|
112
|
+
errors="replace",
|
|
113
|
+
creationflags=creationflags,
|
|
114
|
+
)
|
|
115
|
+
found: asyncio.Future[str] = asyncio.get_running_loop().create_future()
|
|
116
|
+
loop = asyncio.get_running_loop()
|
|
117
|
+
|
|
118
|
+
def pump() -> None:
|
|
119
|
+
# read cloudflared logs until exit; keeps the pipe drained so the process never blocks
|
|
120
|
+
assert self._proc and self._proc.stderr
|
|
121
|
+
for line in self._proc.stderr:
|
|
122
|
+
if not found.done() and (m := URL_RE.search(line)):
|
|
123
|
+
loop.call_soon_threadsafe(found.set_result, m.group(0))
|
|
124
|
+
if not found.done():
|
|
125
|
+
loop.call_soon_threadsafe(found.set_exception, TunnelError("cloudflared exited before giving a URL"))
|
|
126
|
+
|
|
127
|
+
threading.Thread(target=pump, daemon=True).start()
|
|
128
|
+
try:
|
|
129
|
+
self.url = await asyncio.wait_for(found, timeout=self.timeout)
|
|
130
|
+
await self._wait_reachable()
|
|
131
|
+
except BaseException:
|
|
132
|
+
await self.stop()
|
|
133
|
+
raise
|
|
134
|
+
log.info("Tunnel up: %s -> %s", self.url, self.directory)
|
|
135
|
+
return self.url
|
|
136
|
+
|
|
137
|
+
async def _wait_reachable(self) -> None:
|
|
138
|
+
"""New trycloudflare hosts need a few seconds before DNS/edge serve them."""
|
|
139
|
+
probe = next((p.name for p in sorted(self.directory.iterdir()) if p.is_file()), None)
|
|
140
|
+
if probe is None:
|
|
141
|
+
return
|
|
142
|
+
deadline = asyncio.get_running_loop().time() + self.timeout
|
|
143
|
+
async with httpx.AsyncClient(timeout=10) as client:
|
|
144
|
+
while True:
|
|
145
|
+
with contextlib.suppress(httpx.HTTPError):
|
|
146
|
+
r = await client.get(f"{self.url}/{probe}")
|
|
147
|
+
if r.status_code == 200:
|
|
148
|
+
return
|
|
149
|
+
if asyncio.get_running_loop().time() > deadline:
|
|
150
|
+
# Often only the local resolver lags behind for a fresh *.trycloudflare.com host while
|
|
151
|
+
# Meta's fetchers already see it. Continue; if Meta can't fetch, the container reports ERROR.
|
|
152
|
+
log.warning("Tunnel %s not reachable from this machine after %.0fs; continuing", self.url, self.timeout)
|
|
153
|
+
self.locally_reachable = False
|
|
154
|
+
return
|
|
155
|
+
await asyncio.sleep(2)
|
|
156
|
+
|
|
157
|
+
async def stop(self) -> None:
|
|
158
|
+
if self._proc and self._proc.poll() is None:
|
|
159
|
+
self._proc.terminate()
|
|
160
|
+
try:
|
|
161
|
+
await asyncio.to_thread(self._proc.wait, 10)
|
|
162
|
+
except subprocess.TimeoutExpired:
|
|
163
|
+
self._proc.kill()
|
|
164
|
+
self._proc = None
|
|
165
|
+
if self._server:
|
|
166
|
+
self._server.shutdown()
|
|
167
|
+
self._server.server_close()
|
|
168
|
+
self._server = None
|
|
169
|
+
log.info("Tunnel closed")
|
|
@@ -0,0 +1,254 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: creatorloop
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
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
|
|
5
|
+
Project-URL: Homepage, https://github.com/pandich93/creatorloop
|
|
6
|
+
Project-URL: Repository, https://github.com/pandich93/creatorloop
|
|
7
|
+
Project-URL: Issues, https://github.com/pandich93/creatorloop/issues
|
|
8
|
+
Project-URL: Changelog, https://github.com/pandich93/creatorloop/blob/main/CHANGELOG.md
|
|
9
|
+
Author: pandich
|
|
10
|
+
License-Expression: MIT
|
|
11
|
+
License-File: LICENSE
|
|
12
|
+
Keywords: analytics,claude,content-creator,instagram,mcp,model-context-protocol,reels,social-media
|
|
13
|
+
Classifier: Development Status :: 4 - Beta
|
|
14
|
+
Classifier: Environment :: Console
|
|
15
|
+
Classifier: Intended Audience :: Developers
|
|
16
|
+
Classifier: Intended Audience :: End Users/Desktop
|
|
17
|
+
Classifier: Operating System :: OS Independent
|
|
18
|
+
Classifier: Programming Language :: Python :: 3
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
|
+
Classifier: Topic :: Internet
|
|
21
|
+
Classifier: Topic :: Multimedia :: Video
|
|
22
|
+
Requires-Python: >=3.14
|
|
23
|
+
Requires-Dist: httpx>=0.28
|
|
24
|
+
Requires-Dist: mcp<3,>=2.3
|
|
25
|
+
Requires-Dist: pillow>=11.3
|
|
26
|
+
Requires-Dist: python-dotenv>=1.0
|
|
27
|
+
Requires-Dist: tzdata>=2025.2
|
|
28
|
+
Description-Content-Type: text/markdown
|
|
29
|
+
|
|
30
|
+
<!-- mcp-name: io.github.pandich93/creatorloop -->
|
|
31
|
+
<div align="center">
|
|
32
|
+
|
|
33
|
+
# creatorloop
|
|
34
|
+
|
|
35
|
+
**Open-source AI content studio for Instagram creators, built on Claude and the official Instagram API.**
|
|
36
|
+
|
|
37
|
+
Analyse what works → make Reels and carousels → publish or queue them → review how they did. All from a chat with Claude.
|
|
38
|
+
|
|
39
|
+
[](https://github.com/pandich93/creatorloop/actions/workflows/ci.yml)
|
|
40
|
+
[](https://pypi.org/project/creatorloop/)
|
|
41
|
+
[](https://www.python.org/)
|
|
42
|
+
[](LICENSE)
|
|
43
|
+
|
|
44
|
+
[Русский](https://github.com/pandich93/creatorloop/blob/main/README.ru.md) · [Oʻzbekcha](https://github.com/pandich93/creatorloop/blob/main/README.uz.md)
|
|
45
|
+
|
|
46
|
+

|
|
47
|
+
|
|
48
|
+
</div>
|
|
49
|
+
|
|
50
|
+
## Why
|
|
51
|
+
|
|
52
|
+
There are plenty of "Instagram API for Claude" servers. creatorloop is built for the **creator's loop** instead:
|
|
53
|
+
|
|
54
|
+
- **Learn from data, not vibes.** Best and worst posts with their hooks, format comparison, follows per 1,000 reach,
|
|
55
|
+
Reels watch time, best day and hour — and which captions (language, question hook, CTA, length) actually work.
|
|
56
|
+
- **Spy on competitors legally.** Track professional accounts, keep their follower history, and get alerted to the
|
|
57
|
+
posts that did N× better than their median. Analyse any public post by URL, slides included.
|
|
58
|
+
- **Make the content.** A Remotion Reel template with automatic checks (first-second rule, safe zones, "not a copy of
|
|
59
|
+
the carousel"), original music and licensed 3D objects.
|
|
60
|
+
- **Publish safely.** Two-step publishing with a preview, a queue with fingerprints (a changed file blocks the post),
|
|
61
|
+
24 h / 72 h post reviews and comment replies — every public action needs your explicit OK.
|
|
62
|
+
- **Official API only.** No scraping, no browser automation, no risk to your account.
|
|
63
|
+
|
|
64
|
+
## Quick start
|
|
65
|
+
|
|
66
|
+
You need [uv](https://docs.astral.sh/uv/getting-started/installation/), [Claude Desktop](https://claude.ai/download),
|
|
67
|
+
an Instagram **Business or Creator** account linked to a **Facebook Page**, and your own Meta app
|
|
68
|
+
([5-minute guide](https://github.com/pandich93/creatorloop/blob/main/docs/meta-setup.md)).
|
|
69
|
+
|
|
70
|
+
```bash
|
|
71
|
+
uvx --from creatorloop creatorloop-setup # 1. connect to Claude Desktop, create the settings file
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
2. Put your app's `META_APP_ID` and `META_APP_SECRET` into the settings file the command printed.
|
|
75
|
+
3. Save a 60-day token and find your account ID (the short-lived token comes from Graph API Explorer, see the guide):
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
uvx --from creatorloop creatorloop-auth exchange --short-token <TOKEN> --write
|
|
79
|
+
uvx --from creatorloop creatorloop-auth whoami --write
|
|
80
|
+
uvx --from creatorloop creatorloop-auth check # → OK: @your_account followers=...
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
Restart Claude Desktop and ask: *"How did my last 10 posts do, and what should I post next?"*
|
|
84
|
+
|
|
85
|
+
<details>
|
|
86
|
+
<summary>Installing uv</summary>
|
|
87
|
+
|
|
88
|
+
| System | Command |
|
|
89
|
+
|---|---|
|
|
90
|
+
| Windows | `powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex"` |
|
|
91
|
+
| macOS | `brew install uv` or `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
|
|
92
|
+
| Linux | `curl -LsSf https://astral.sh/uv/install.sh \| sh` |
|
|
93
|
+
|
|
94
|
+
uv downloads Python 3.14 by itself if you don't have it.
|
|
95
|
+
</details>
|
|
96
|
+
|
|
97
|
+
`creatorloop-setup` finds the Claude Desktop config on Windows (including the Microsoft Store build), macOS and Linux,
|
|
98
|
+
keeps your other servers, makes a backup and creates your settings file. Claude Desktop rewrites its config while it
|
|
99
|
+
runs, so on macOS the command quits and reopens it for you; on Windows and Linux it asks you to quit it first.
|
|
100
|
+
|
|
101
|
+
## What you can ask
|
|
102
|
+
|
|
103
|
+
- "Make a report on my content for the last 60 days. Reels or carousels — what works better, and when should I post?"
|
|
104
|
+
- "Compare me with @competitor1 and @competitor2. Who has the higher engagement and why?"
|
|
105
|
+
- "Analyse this post https://www.instagram.com/p/… and write my own version of it."
|
|
106
|
+
- "Track @competitor and tell me every week which of their posts took off."
|
|
107
|
+
- "Check the hashtags #ai, #productivity and #startup. Check the quota first."
|
|
108
|
+
- "Queue the post from folder `my-first-reel` for the next free slot." → preview → "yes" → it goes out on time.
|
|
109
|
+
- "Which new comments haven't I answered? Draft replies." → you approve each reply.
|
|
110
|
+
|
|
111
|
+
Ready-made prompts in Claude Desktop's **+** menu: *Weekly Instagram report*, *Competitor brief*, *Data-driven content ideas*.
|
|
112
|
+
|
|
113
|
+
## Tools
|
|
114
|
+
|
|
115
|
+
| Area | Tools |
|
|
116
|
+
|---|---|
|
|
117
|
+
| Your account | `get_my_profile`, `get_my_media`, `get_media_insights`, `get_account_insights`, `get_audience_demographics` |
|
|
118
|
+
| Content analysis | `get_my_content_report`, `get_caption_insights`, `get_post_history`, `post_reviews` |
|
|
119
|
+
| Competitors | `get_competitor`, `compare_accounts`, `get_follower_history`, `track_competitor`, `untrack_competitor`, `list_tracked_competitors`, `update_tracked_competitors`, `find_viral_posts`, `get_competitor_post` |
|
|
120
|
+
| Hashtags | `search_hashtag`, `compare_hashtags`, `plan_hashtag_research` |
|
|
121
|
+
| Publishing | `prepare_post`, `get_post_job`, `publish_media`, `list_publications` |
|
|
122
|
+
| Queue | `queue_post`, `list_queue`, `cancel_queued` |
|
|
123
|
+
| Comments | `get_new_comments`, `reply_comment` |
|
|
124
|
+
| Service | `get_api_status`, `clear_cache`, `restart_server` |
|
|
125
|
+
|
|
126
|
+
33 tools in total. Tools that change something on Instagram are annotated as such for Claude, and their descriptions
|
|
127
|
+
tell it to act only after you approve: `publish_media` and `reply_comment` after you OK the preview or the exact
|
|
128
|
+
text, `queue_post` only with `confirm=true` after you saw the preview.
|
|
129
|
+
|
|
130
|
+
## Publishing
|
|
131
|
+
|
|
132
|
+
Put the files into a folder inside your **content folder** (`<creatorloop home>/content/<name>/`):
|
|
133
|
+
|
|
134
|
+
```
|
|
135
|
+
my-carousel/ my-reel/
|
|
136
|
+
slide_01.png … slide_10.png reel.mp4 # H.264/HEVC, 23–60 fps, ≤1920 px wide, 3 s–15 min, ≤300 MB
|
|
137
|
+
caption.txt caption.txt
|
|
138
|
+
reel.json # optional: {"cover_ms": 1667, "share_to_feed": true, "trial": "SS_PERFORMANCE"}
|
|
139
|
+
```
|
|
140
|
+
|
|
141
|
+
- Slides: 1–10 PNG/JPG (API limit), aspect ratio 4:5 to 1.91:1, ordered by file name. Everything below a `---` line in
|
|
142
|
+
`caption.txt` is notes and is not published.
|
|
143
|
+
- Then: "prepare the post from folder `my-carousel`" → preview → "publish". Or queue it for a slot.
|
|
144
|
+
- Carousels: Instagram downloads images from a public URL, so creatorloop opens a temporary
|
|
145
|
+
[Cloudflare Quick Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/do-more-with-tunnels/trycloudflare/)
|
|
146
|
+
for that minute. Install `cloudflared` once: `winget install --id Cloudflare.cloudflared -e` (Windows),
|
|
147
|
+
`brew install cloudflared` (macOS) or a package from [pkg.cloudflare.com](https://pkg.cloudflare.com/index.html) (Linux).
|
|
148
|
+
- Reels upload directly to Meta (no tunnel). The MP4 header is checked before upload (duration, size, width,
|
|
149
|
+
`moov` first) with the exact `ffmpeg` fix if something is off.
|
|
150
|
+
- Queue slots default to Tue/Thu/Sun 19:00 in your timezone — an example, change `QUEUE_SLOTS` in the settings file.
|
|
151
|
+
A queued post is blocked if its files or caption change after you approved it, and is marked missed if your
|
|
152
|
+
computer was asleep for more than 3 hours past the slot.
|
|
153
|
+
- Meta's limit is 100 posts per rolling 24 hours; `list_publications` shows what is left. Publishing is never retried
|
|
154
|
+
automatically, so there are no duplicates.
|
|
155
|
+
|
|
156
|
+
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) —
|
|
157
|
+
a sample carousel, a sample Reel storyboard and the Remotion Reel template.
|
|
158
|
+
|
|
159
|
+
## What the Instagram API allows (and doesn't)
|
|
160
|
+
|
|
161
|
+
| | Possible | Not possible |
|
|
162
|
+
|---|---|---|
|
|
163
|
+
| **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 |
|
|
164
|
+
| **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 |
|
|
165
|
+
| **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 |
|
|
166
|
+
| **Follower growth** | creatorloop saves a daily snapshot for you and every competitor you look at | History before the first snapshot |
|
|
167
|
+
|
|
168
|
+
Engagement rate for your posts = Σ(likes + comments + saves + shares) / Σreach × 100 (weighted, so tiny posts don't
|
|
169
|
+
skew it). Posts younger than 72 h are reported separately as "still growing". Competitors' ER is per follower — the
|
|
170
|
+
API does not expose their reach.
|
|
171
|
+
|
|
172
|
+
## Settings
|
|
173
|
+
|
|
174
|
+
`creatorloop-setup` creates `.env` in your creatorloop home folder:
|
|
175
|
+
|
|
176
|
+
| System | Home folder |
|
|
177
|
+
|---|---|
|
|
178
|
+
| Windows | `%APPDATA%\creatorloop` |
|
|
179
|
+
| macOS | `~/Library/Application Support/creatorloop` |
|
|
180
|
+
| Linux | `~/.local/share/creatorloop` (or `$XDG_DATA_HOME/creatorloop`) |
|
|
181
|
+
|
|
182
|
+
Set `CREATORLOOP_HOME` to use another folder. The home folder holds `.env`, the `creatorloop.db` database and the
|
|
183
|
+
`content/` folder.
|
|
184
|
+
|
|
185
|
+
| Variable | Required | Meaning |
|
|
186
|
+
|---|---|---|
|
|
187
|
+
| `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) |
|
|
188
|
+
| `IG_USER_ID` | yes | Your Instagram professional account ID (`1784…`), not the username |
|
|
189
|
+
| `GRAPH_API_VERSION` | no | Default `v26.0` |
|
|
190
|
+
| `META_APP_ID`, `META_APP_SECRET` | no | Only for `creatorloop-auth exchange` |
|
|
191
|
+
| `IG_TIMEZONE` | no | IANA name, e.g. `Europe/Berlin`. Default: your computer's timezone |
|
|
192
|
+
| `QUEUE_SLOTS` | no | e.g. `Mon,Wed,Fri 20:00` |
|
|
193
|
+
| `IG_DB_PATH`, `CACHE_TTL_*_MIN` | no | Database location, cache lifetime in minutes |
|
|
194
|
+
|
|
195
|
+
The token expiry shows up in `get_api_status`, and every tool answer carries a `token_warning` 14 days before expiry.
|
|
196
|
+
|
|
197
|
+
## FAQ
|
|
198
|
+
|
|
199
|
+
<details><summary>Does it work with a personal Instagram account?</summary>
|
|
200
|
+
No. Meta's API only serves Business and Creator accounts linked to a Facebook Page. Switching is free:
|
|
201
|
+
Instagram → Settings → Account type and tools.
|
|
202
|
+
</details>
|
|
203
|
+
|
|
204
|
+
<details><summary>Do I need Meta App Review?</summary>
|
|
205
|
+
Not for your own account: keep the app in Development mode, you are its admin. Hashtag search may require the
|
|
206
|
+
"Instagram Public Content Access" feature for some accounts — creatorloop tells you if Meta refuses it.
|
|
207
|
+
</details>
|
|
208
|
+
|
|
209
|
+
<details><summary>Can it get my account banned?</summary>
|
|
210
|
+
creatorloop uses only the official Graph API with your own app and token, within Meta's rate limits. It does no
|
|
211
|
+
scraping and no browser automation.
|
|
212
|
+
</details>
|
|
213
|
+
|
|
214
|
+
<details><summary>Which AI clients does it work with?</summary>
|
|
215
|
+
It is a standard MCP server (stdio). It is developed and tested with Claude Desktop; other MCP clients that support
|
|
216
|
+
stdio servers should work too.
|
|
217
|
+
</details>
|
|
218
|
+
|
|
219
|
+
<details><summary>A metric is missing in the answer.</summary>
|
|
220
|
+
Meta regularly removes metrics (e.g. `impressions` and `plays` in April 2025, replaced by `views`). creatorloop
|
|
221
|
+
moves a refused metric to `unavailable` instead of failing and stops asking for it for 7 days. Insights can lag up to 48 h.
|
|
222
|
+
</details>
|
|
223
|
+
|
|
224
|
+
## Data & privacy
|
|
225
|
+
|
|
226
|
+
- Your token, settings, database and content stay on your computer in the creatorloop home folder.
|
|
227
|
+
- creatorloop talks to Meta only: the Instagram Graph API (`graph.facebook.com`, `rupload.facebook.com` for video
|
|
228
|
+
uploads) and Instagram's media servers when it downloads the slides of a post you asked it to analyse.
|
|
229
|
+
- To publish carousels (and Reels, if the direct upload is refused) it opens a temporary Cloudflare Quick Tunnel to
|
|
230
|
+
your local files for the minute Meta needs to fetch them, then closes it and deletes the temporary copies.
|
|
231
|
+
- No analytics, telemetry or third-party services.
|
|
232
|
+
|
|
233
|
+
## Development
|
|
234
|
+
|
|
235
|
+
```bash
|
|
236
|
+
git clone https://github.com/pandich93/creatorloop && cd creatorloop
|
|
237
|
+
uv sync
|
|
238
|
+
uv run pytest # offline: mocked Graph API and captured response shapes
|
|
239
|
+
uv run creatorloop-setup # points Claude Desktop at this checkout instead of the PyPI package
|
|
240
|
+
```
|
|
241
|
+
|
|
242
|
+
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).
|
|
243
|
+
|
|
244
|
+
## Disclaimer
|
|
245
|
+
|
|
246
|
+
creatorloop is an independent open-source project. **Not affiliated with, endorsed or sponsored by Meta or
|
|
247
|
+
Instagram.** "Instagram" is a trademark of Meta Platforms, Inc. You are responsible for complying with the
|
|
248
|
+
[Meta Platform Terms](https://developers.facebook.com/terms/) and Instagram's policies when you use it.
|
|
249
|
+
|
|
250
|
+
## License
|
|
251
|
+
|
|
252
|
+
[MIT](https://github.com/pandich93/creatorloop/blob/main/LICENSE). The Reel template in `examples/reel-template` uses [Remotion](https://www.remotion.dev), which has
|
|
253
|
+
its own licence; bundled assets and fonts are listed in
|
|
254
|
+
[`examples/reel-template/public/assets/LICENSES.md`](https://github.com/pandich93/creatorloop/blob/main/examples/reel-template/public/assets/LICENSES.md).
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
creatorloop/__init__.py,sha256=OBx2bD7OqDizKyRZ0dCJwQuxb5rxoISywyOxQgTSbWI,609
|
|
2
|
+
creatorloop/__main__.py,sha256=sEPDF1bCIYADjVPxs-GYsqdc9Ka78Km4jH9i7oMqIBk,44
|
|
3
|
+
creatorloop/analytics.py,sha256=icoX-eBx-gxxVuPurPRutwNyVr_miYF7N5dMunci3Vo,23839
|
|
4
|
+
creatorloop/auth_cli.py,sha256=F17wFKWw1Sm-OxhnJ23MfTla_xXRneyKloVN_SmcAZ0,4900
|
|
5
|
+
creatorloop/comments.py,sha256=dES7SbTzun2DupLSfJ4d_WKULu_L47CE7AUgqodPeR0,4901
|
|
6
|
+
creatorloop/config.py,sha256=2VuUxc1an8WSAgBbDG3X0uhhWKaCpyOMIhcje7tz-KQ,3800
|
|
7
|
+
creatorloop/env.example,sha256=T56bUCihTB_NPKWyL8ibYnjTFOTLBPDCvS3nw56qZtY,1380
|
|
8
|
+
creatorloop/graph_client.py,sha256=0WBZaaZizdggwOnyBYdCkHAzENh3s9YmxblPWhCIu1o,8852
|
|
9
|
+
creatorloop/instagram.py,sha256=RQ6nRTF7IMrqVRiQyvQvZu7qIpRS9SPP_AgxeTKGn40,20589
|
|
10
|
+
creatorloop/paths.py,sha256=WggF0W_QYS2DqCj-XgnvRWghM4HM99BgoCTAOFhyadY,2274
|
|
11
|
+
creatorloop/post_queue.py,sha256=ngNwRiPO9qm2m9g4_dvirSavAbAENkUSPCk-FQJrXp8,7914
|
|
12
|
+
creatorloop/publish.py,sha256=0DQFHhoigQ6Ky9YG_8DpMyH5h1BZ3RaVD6uMhgJdyL0,19427
|
|
13
|
+
creatorloop/refs.py,sha256=kjZv8A4ZXDXnVt1cvVuf7PPh6CLsmxfkiA4SMrEL_eA,7825
|
|
14
|
+
creatorloop/reviews.py,sha256=OYihgV8OxWMfp3uuXtpDksXy9snV0w8rtNBPcTpH6ho,4890
|
|
15
|
+
creatorloop/server.py,sha256=eEY6VVWbkGDcNtbG6FWec8kekclq8cZpPpev3eAoHKM,39973
|
|
16
|
+
creatorloop/setup_cli.py,sha256=1OuXC0MDYtUqge8vn02oqC0_E7lagfdRgec_sJbp2ec,7349
|
|
17
|
+
creatorloop/storage.py,sha256=f4UOO1Gcur8mEfWcqWthsb76XpDUvV4oajDFCEWX-Zk,19693
|
|
18
|
+
creatorloop/tunnel.py,sha256=SvDYdkruERTAicatdqg2xzXblfR6Kdb_PIpUGou9ruc,7058
|
|
19
|
+
creatorloop-0.1.0.dist-info/METADATA,sha256=zJQU5GH5QBl3fWuHmi2XIxWs_WK5ZiJbQSo_wzt0dDs,14558
|
|
20
|
+
creatorloop-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
|
|
21
|
+
creatorloop-0.1.0.dist-info/entry_points.txt,sha256=TKJGQT5TrgypBN98WwjbSOqNR6ugT8B1fRJlT-Pen0E,148
|
|
22
|
+
creatorloop-0.1.0.dist-info/licenses/LICENSE,sha256=Rsow3mW5cXEqSSWIZUa5mhG79uK2O4LS6axiFJj-mDA,1064
|
|
23
|
+
creatorloop-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 pandich
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|