insta-edits 0.1.0__tar.gz

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.
@@ -0,0 +1,31 @@
1
+ {
2
+ "name": "insta-edits",
3
+ "owner": {
4
+ "name": "Faisal Khan",
5
+ "url": "https://github.com/faisalkhanzemi"
6
+ },
7
+ "description": "Claude Code plugin for Instagram Edits for Mac: let Claude edit your Reels.",
8
+ "plugins": [
9
+ {
10
+ "name": "insta-edits",
11
+ "source": "./",
12
+ "description": "Let Claude edit your Instagram Reels in Edits for Mac: cut to the beat, captions, text, transitions, zooms and export, with the full 274-tool editor. Keeps Claude's tool list in sync and your token in the keychain.",
13
+ "category": "media",
14
+ "tags": [
15
+ "instagram",
16
+ "instagram-edits",
17
+ "edits",
18
+ "reels",
19
+ "instagram-reels",
20
+ "video-editing",
21
+ "video-editor",
22
+ "captions",
23
+ "content-creator",
24
+ "mcp",
25
+ "mcp-server",
26
+ "macos",
27
+ "claude-code"
28
+ ]
29
+ }
30
+ ]
31
+ }
@@ -0,0 +1,51 @@
1
+ {
2
+ "name": "insta-edits",
3
+ "displayName": "Insta Edits for Claude",
4
+ "version": "0.1.0",
5
+ "description": "Let Claude edit your Instagram Reels in Edits for Mac: cut to the beat, captions, text, transitions, zooms and export, with the full 274-tool editor. Keeps Claude's tool list in sync and your token in the keychain.",
6
+ "author": {
7
+ "name": "Faisal Khan",
8
+ "url": "https://github.com/faisalkhanzemi"
9
+ },
10
+ "homepage": "https://github.com/faisalkhanzemi/insta-edits-for-claude",
11
+ "repository": "https://github.com/faisalkhanzemi/insta-edits-for-claude",
12
+ "license": "MIT",
13
+ "keywords": [
14
+ "instagram",
15
+ "instagram-edits",
16
+ "edits",
17
+ "reels",
18
+ "instagram-reels",
19
+ "video-editing",
20
+ "video-editor",
21
+ "captions",
22
+ "content-creator",
23
+ "mcp",
24
+ "mcp-server",
25
+ "macos",
26
+ "claude-code"
27
+ ],
28
+ "userConfig": {
29
+ "edits_token": {
30
+ "type": "string",
31
+ "title": "Edits access token",
32
+ "description": "In Edits: Settings > Automation > Enable Automation Server, then copy the Access token. Stored in your system keychain, never in a file or a chat.",
33
+ "sensitive": true,
34
+ "required": true
35
+ }
36
+ },
37
+ "mcpServers": {
38
+ "edits": {
39
+ "command": "python3",
40
+ "args": [
41
+ "-m",
42
+ "insta_edits",
43
+ "serve"
44
+ ],
45
+ "env": {
46
+ "PYTHONPATH": "${CLAUDE_PLUGIN_ROOT}/src",
47
+ "EDITS_MCP_TOKEN": "${user_config.edits_token}"
48
+ }
49
+ }
50
+ }
51
+ }
@@ -0,0 +1,10 @@
1
+ __pycache__/
2
+ *.py[cod]
3
+ .venv/
4
+ .pytest_cache/
5
+ .ruff_cache/
6
+ dist/
7
+ build/
8
+ *.egg-info/
9
+ .DS_Store
10
+ token
@@ -0,0 +1,17 @@
1
+ # Changelog
2
+
3
+ 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/).
4
+
5
+ ## [0.1.0] - 2026-11-07
6
+
7
+ ### Added
8
+ - Stdio MCP bridge to the Edits for Mac automation server (Streamable HTTP), standard library only, Python 3.9+.
9
+ - Tool-set sync: Edits declares `tools.listChanged` but never sends it, so the bridge re-lists tools after every call and sends `notifications/tools/list_changed` when Edits moves between home (32 tools) and the editor (274 tools). `serve --no-sync` turns it off.
10
+ - Reply normalisation: drops `"resultType": "complete"` when Edits sends it without `ttlMs`/`cacheScope`, which some Claude Code builds rejected with `Invalid result for tools/list`.
11
+ - Forwarding of a server-to-client notification stream if Edits ever offers one (`serve --no-stream` turns it off).
12
+ - Session and `MCP-Protocol-Version` header handling, JSON and event-stream replies, batch requests.
13
+ - Clear JSON-RPC errors when Edits is closed or the token is rejected; the token is never logged.
14
+ - `doctor` command (with `--json` for bug reports) and `set-token` (hidden prompt, file saved with 0600 permissions).
15
+ - Claude Code plugin with a keychain-stored token prompt, a marketplace manifest, and an `edits` skill with notes measured against Edits 454: sandboxed import folders, absolute paths, HDR projects, beat detection fallback, keyframe and export formats, and library music in automation exports.
16
+
17
+ [0.1.0]: https://github.com/faisalkhanzemi/insta-edits-for-claude/releases/tag/v0.1.0
@@ -0,0 +1,28 @@
1
+ # Contributing
2
+
3
+ Thanks for helping. Edits for Mac ships weekly, so the most useful contributions are reports of what changed.
4
+
5
+ ## Reporting a problem
6
+
7
+ Run this and paste the output in the issue (it contains no secrets):
8
+
9
+ ```bash
10
+ insta-edits doctor --json
11
+ ```
12
+
13
+ Include your Edits version (Edits > About Edits) and your Claude Code version (`claude --version`).
14
+
15
+ ## Development
16
+
17
+ ```bash
18
+ git clone https://github.com/faisalkhanzemi/insta-edits-for-claude
19
+ cd insta-edits-for-claude
20
+ python3 -m venv .venv && . .venv/bin/activate
21
+ pip install -e ".[dev]"
22
+ pytest
23
+ ruff check . && ruff format --check .
24
+ ```
25
+
26
+ The tests run against `tests/fake_edits.py`, a stand-in server that mirrors what the real Edits server does, so you don't need Edits installed to run them. When Edits changes its behaviour, update the fake first, then the bridge.
27
+
28
+ Keep the bridge on the standard library only and compatible with Python 3.9 (the version macOS ships).
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Faisal Khan
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.
@@ -0,0 +1,229 @@
1
+ Metadata-Version: 2.5
2
+ Name: insta-edits
3
+ Version: 0.1.0
4
+ Summary: Let Claude Code and other MCP clients edit Instagram Reels in Edits for Mac, through its built-in MCP server.
5
+ Project-URL: Homepage, https://github.com/faisalkhanzemi/insta-edits-for-claude
6
+ Project-URL: Issues, https://github.com/faisalkhanzemi/insta-edits-for-claude/issues
7
+ Project-URL: Changelog, https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/CHANGELOG.md
8
+ Author: Faisal Khan
9
+ License-Expression: MIT
10
+ License-File: LICENSE
11
+ Keywords: claude,claude-code,edits,instagram,instagram-edits,instagram-reels,macos,mcp,mcp-server,model-context-protocol,reels,video-editing
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Environment :: Console
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: Operating System :: MacOS
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3 :: Only
18
+ Classifier: Topic :: Multimedia :: Video :: Non-Linear Editor
19
+ Requires-Python: >=3.9
20
+ Provides-Extra: dev
21
+ Requires-Dist: pytest>=8; extra == 'dev'
22
+ Requires-Dist: ruff>=0.6; extra == 'dev'
23
+ Description-Content-Type: text/markdown
24
+
25
+ # Insta Edits for Claude
26
+
27
+ <!-- mcp-name: io.github.faisalkhanzemi/insta-edits -->
28
+
29
+ **Let Claude Code edit in Instagram Edits for Mac, with the full editor and not just the home screen.**
30
+
31
+ [![CI](https://github.com/faisalkhanzemi/insta-edits-for-claude/actions/workflows/ci.yml/badge.svg)](https://github.com/faisalkhanzemi/insta-edits-for-claude/actions/workflows/ci.yml)
32
+ ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
33
+ ![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
34
+ [![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/LICENSE)
35
+
36
+ <p align="center"><a href="https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/assets/hero.mp4"><img src="https://raw.githubusercontent.com/faisalkhanzemi/insta-edits-for-claude/main/assets/hero.gif" alt="A real Claude Code session making a beat-synced Dubai in 15 seconds reel inside Instagram Edits for Mac: clips cut on the beat, punch-in zooms, a speed ramp, a title and labels, frame checks, then export" width="100%"></a></p>
37
+
38
+ <p align="center"><sub>One prompt, a real Claude Code session, nothing scripted. Edits found no beats, so Claude analysed the music itself (122 BPM), cut every clip on a beat, checked its own frames and exported the reel. <a href="https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/assets/hero.mp4">Watch with sound</a>.</sub></p>
39
+
40
+ Edits for Mac, which Meta launched on 5 November 2026, has a built-in automation server that speaks MCP: in Meta's words, you can connect AI agents "to the desktop editor through MCP so they can help with your projects". You can point Claude Code at it directly, but you only get part of it.
41
+
42
+ Edits changes its tools with the screen. The home screen offers **32 tools**: projects, imports and catalogs. Open a project and it offers **274**, with text, captions, effects, transitions, keyframes, audio and export. Edits says it will announce that change (`tools.listChanged: true`) but never sends the notification. Claude keeps the 32 home tools for the whole session and never sees the editor.
43
+
44
+ This bridge sits between the two. After every tool call it asks Edits which tools it offers now. If the set has changed, it tells Claude, and Claude refreshes the list. It also fixes a reply format that some Claude Code builds reject, gives readable errors, and keeps your token out of config files.
45
+
46
+ ```
47
+ Claude Code ──stdio──▶ insta-edits ──HTTP──▶ Edits for Mac (127.0.0.1:19501)
48
+ ◀── tools/list_changed ──┘ checks the tool set after each call
49
+ ```
50
+
51
+ **Works with** Claude Code in the terminal and in the Code tab of the Claude desktop app. It's a standard stdio MCP server, so other MCP clients (the Claude desktop chat, Cursor, Codex) can run `insta-edits serve` too, though we've only tested Claude Code.
52
+
53
+ ## What you get
54
+
55
+ - **The full editor.** Claude receives `notifications/tools/list_changed` as soon as Edits moves between home (32 tools) and the editor (274). Without the bridge, that notification never arrives.
56
+ - **Replies that every Claude Code build accepts.** Edits marks each result `"resultType": "complete"` without the caching fields that newer MCP schemas pair with it. Some Claude Code builds then dropped every tool, with `Invalid result for tools/list: ttlMs … cacheScope`. The bridge removes the marker only when those fields are missing.
57
+ - **Your token stays private.** The plugin keeps it in the macOS keychain. The CLI keeps it in a `0600` file. It never appears in `~/.claude.json`, in logs or in error messages.
58
+ - **Errors you can act on.** "Cannot reach Edits: open it and enable the Automation Server" replaces a stack trace. A rejected token says how to update it.
59
+ - **`doctor` checks every link** from the app to the sign-in, and `--json` gives you a report to attach to a bug.
60
+ - **An `edits` skill** that teaches Claude how the server behaves: discover before guessing, work in normalised canvas coordinates, check rendered frames, and **never publish without your explicit go-ahead**.
61
+ - **Python standard library only.** Nothing to `pip install` for the plugin, and it runs on the `python3` that comes with macOS.
62
+
63
+ ## Requirements
64
+
65
+ - A Mac with Apple silicon (M1 or later) and [Edits for Mac](https://edits.instagram.com/desktop), free and signed in to Instagram
66
+ - Claude Code
67
+ - `python3` 3.9 or newer. Run `xcode-select --install` if macOS asks for the command line tools.
68
+
69
+ ## Install
70
+
71
+ ### 1. Turn on the automation server in Edits
72
+
73
+ Go to **Edits › Settings › Automation**, switch on **Enable Automation Server**, and copy the **Access token**. Keep Edits open while Claude works.
74
+
75
+ ### 2a. As a Claude Code plugin (recommended)
76
+
77
+ Start `claude` in a terminal and type:
78
+
79
+ ```
80
+ /plugin marketplace add faisalkhanzemi/insta-edits-for-claude
81
+ /plugin install insta-edits@insta-edits
82
+ ```
83
+
84
+ Claude Code asks for the access token with a masked prompt and stores it in your keychain. Restart Claude Code, then run `/mcp`: `edits` should show as connected. The plugin also installs the `edits` skill.
85
+
86
+ <details>
87
+ <summary>Installing from a shell script, or using the Claude desktop app</summary>
88
+
89
+ The shell commands do the same thing but don't prompt for the token, so set it afterwards with `/plugin configure insta-edits@insta-edits` inside Claude Code:
90
+
91
+ ```bash
92
+ claude plugin marketplace add faisalkhanzemi/insta-edits-for-claude
93
+ ```
94
+
95
+ ```bash
96
+ claude plugin install insta-edits@insta-edits
97
+ ```
98
+
99
+ A plugin installed this way, at user scope, also shows up in the Code tab of the Claude desktop app, which reads the same settings.
100
+ </details>
101
+
102
+ ### 2b. As a standalone MCP server
103
+
104
+ ```bash
105
+ pipx install git+https://github.com/faisalkhanzemi/insta-edits-for-claude
106
+ ```
107
+
108
+ ```bash
109
+ insta-edits set-token
110
+ ```
111
+
112
+ ```bash
113
+ claude mcp add --scope user edits -- insta-edits serve
114
+ ```
115
+
116
+ `set-token` asks for the token with a hidden prompt and saves it to `~/.config/insta-edits/token` with `0600` permissions. Never put the token itself on the `claude mcp add` line: it would end up in plain text in `~/.claude.json` and in your shell history.
117
+
118
+ ## Check the connection
119
+
120
+ ```bash
121
+ insta-edits doctor
122
+ ```
123
+
124
+ ```
125
+ insta-edits 0.1.0 doctor
126
+
127
+ ✓ macOS 27.0.1
128
+ ✓ Edits app installed /Applications/Edits.app
129
+ ✓ Automation server answering at http://127.0.0.1:19501/mcp (HTTP 403 without a token, as expected)
130
+ ✓ Access token from ~/.config/insta-edits/token
131
+ ✓ Sign-in metapilot-native 1.0.0, protocol 2025-06-18
132
+ ✓ Tools 32 on the current screen (home screen; Edits offers more once a project is open)
133
+ ✓ Reply format normalised for older Claude Code builds (resultType without caching fields)
134
+ ✓ Edits automation schema 2026.10.19-1
135
+ ✓ Tool-change notifications Edits announces them but never sends any; the bridge checks after each call and tells Claude
136
+
137
+ All good. Claude can drive Edits.
138
+ ```
139
+
140
+ Each `✗` line names its fix. Plugin users who want `doctor` can install the CLI as in 2b. The plugin token lives in the keychain, so without `set-token` the doctor checks stop at the sign-in step.
141
+
142
+ ## Using it
143
+
144
+ Ask for edits in plain words:
145
+
146
+ > Open my latest Edits project and tell me what's on the timeline.
147
+
148
+ > Import `~/Movies/broll/` into a new project, cut it to the beat of the voice-over, and add word-by-word captions in a clean sans.
149
+
150
+ > Add a soft zoom on every product close-up and a whoosh on each cut, then render a preview so I can check the frames.
151
+
152
+ Claude opens the project, the editor tools appear, and it works from them. It doesn't post. Publishing stays in the Edits window unless you explicitly tell Claude to share a specific video.
153
+
154
+ ## How it works
155
+
156
+ | Step | What happens |
157
+ | --- | --- |
158
+ | Session | The bridge forwards `initialize`, keeps Edits' `Mcp-Session-Id`, and sends `MCP-Protocol-Version` on every request. |
159
+ | Replies | It accepts both JSON and `text/event-stream` replies and batch requests, and normalises `resultType` only when the caching fields are missing. |
160
+ | Tool sync | After each `tools/call` it sends its own `tools/list` to Edits, using an id Claude never sees, and compares the tool names. If they changed, it writes `notifications/tools/list_changed` to Claude. Turn this off with `serve --no-sync`. |
161
+ | Notifications | If a future Edits build opens a server-to-client stream, the bridge listens on it and forwards what arrives. Edits doesn't offer one today, so the bridge stops trying after the first refusal. Turn it off with `serve --no-stream`. |
162
+ | Errors | When Edits is closed the bridge returns JSON-RPC `-32001`. When Edits returns an HTTP error it returns `-32002`. Both carry a one-line fix. |
163
+
164
+ Settings come from the environment: `EDITS_MCP_URL` (default `http://127.0.0.1:19501/mcp`), `EDITS_MCP_TOKEN`, and `EDITS_MCP_TOKEN_FILE`. Logs go to stderr.
165
+
166
+ ## Tested with
167
+
168
+ | | Version |
169
+ | --- | --- |
170
+ | Edits for Mac | 454.0.0 (server `metapilot-native` 1.0.0, automation schema 2026.10.19-1) |
171
+ | Claude Code | 2.1.296 |
172
+ | macOS | 27.0.1 |
173
+ | Python | 3.9.6 (system), 3.11, 3.13 in CI |
174
+
175
+ Edits updates often and its automation server is undocumented. If a new build breaks something, run `insta-edits doctor --json` and [open an issue](https://github.com/faisalkhanzemi/insta-edits-for-claude/issues/new/choose) with the output. It contains no token.
176
+
177
+ ## Troubleshooting
178
+
179
+ | Symptom | Fix |
180
+ | --- | --- |
181
+ | `Cannot reach Edits` | Open Edits and switch on Settings › Automation › Enable Automation Server. |
182
+ | HTTP 401 or 403 | The token changed in Edits. Update it in `/plugin`, or run `insta-edits set-token`. |
183
+ | Only home tools, even with a project open | Check that `edits` in `/mcp` points to the bridge and not straight at `127.0.0.1:19501`, and that you didn't start it with `--no-sync`. |
184
+ | Import fails with `file not found: ~/…` | Edits doesn't expand `~`. Pass the full path, such as `/Users/you/Movies/clip.mp4`. |
185
+ | Import fails with `Sandbox bookmark unavailable` | Edits is sandboxed. In our tests it imported from `~/Movies` and refused `~/Downloads`, `~/Desktop`, temp folders and project folders. Move the footage into `~/Movies` and import it from there. |
186
+ | Exported video is silent where the song should be | Songs from Edits' music library come in as licensed tracks, and exports started through automation leave them out: the music bed was silent in every test, while our own audio files exported fine. Export or post from the Edits window when a library song matters. |
187
+ | `addSongToComposition` adds a different song | Passing a track id sometimes added another track. Passing the exact title added the right song in our test. |
188
+
189
+ ## Security
190
+
191
+ - The bridge only connects to the URL you configure, which defaults to `127.0.0.1`. It sends nothing anywhere else and has no telemetry.
192
+ - The token is redacted in every log line, error message and `repr`. `doctor --json` reports where the token came from, never its value.
193
+ - Edits is signed in to your Instagram account. The bundled skill tells Claude never to publish, share or schedule without your explicit go-ahead for that specific post.
194
+ - Report vulnerabilities privately as described in [SECURITY.md](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/SECURITY.md).
195
+
196
+ ## FAQ
197
+
198
+ **How do I connect Claude to Instagram Edits?** Install Edits for Mac, switch on Settings › Automation › Enable Automation Server, then add this plugin with the two `/plugin` lines under [Install](#install). Claude can then open your projects and edit them.
199
+
200
+ **Can Claude edit Instagram Reels?** Yes, inside Edits for Mac. It can import clips, cut them on the beat, add captions, text, transitions, zooms and speed ramps, check rendered frames and export. You post the reel from Edits yourself.
201
+
202
+ **Does it work with claude.ai in the browser?** No. Edits runs on your Mac and only listens locally, so it needs Claude Code (or another MCP client) running on the same Mac.
203
+
204
+ **Is this official?** No. It's an independent open-source project, not affiliated with or endorsed by Meta, Instagram or Anthropic. "Instagram" and "Edits" are trademarks of Meta Platforms, Inc.
205
+
206
+ **Does it work on Windows or with the Edits phone app?** No. Edits on desktop is only available on macOS, and the automation server only exists there.
207
+
208
+ **Do I still need this if my Claude Code build accepts Edits' replies?** Yes, for the editor tools. Edits never announces that its tools changed, and no client can find that out without asking.
209
+
210
+ **Can Claude post to Instagram for me?** The bridge won't stop Claude from calling Edits' share tools, but the bundled skill tells it to wait for your explicit go-ahead. Posting from the Edits window is the safer default.
211
+
212
+ ## Development
213
+
214
+ ```bash
215
+ git clone https://github.com/faisalkhanzemi/insta-edits-for-claude && cd insta-edits-for-claude
216
+ python3 -m venv .venv && . .venv/bin/activate
217
+ pip install -e . pytest ruff
218
+ pytest && ruff check . && ruff format --check .
219
+ ```
220
+
221
+ The tests run against `tests/fake_edits.py`, a stand-in that behaves like the real server: it sends no notifications, changes its tool set when a project opens, and replies with `resultType`. You don't need a Mac or Edits to run them. See [CONTRIBUTING.md](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/CONTRIBUTING.md).
222
+
223
+ ## Credits
224
+
225
+ Demo footage: stock clips from [Pexels](https://www.pexels.com/license/) (Pexels License). Music: "Tech House vibes" by Alejandro Magaña, [Mixkit](https://mixkit.co/license/) (Mixkit License).
226
+
227
+ ## License
228
+
229
+ [MIT](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/LICENSE) © Faisal Khan
@@ -0,0 +1,205 @@
1
+ # Insta Edits for Claude
2
+
3
+ <!-- mcp-name: io.github.faisalkhanzemi/insta-edits -->
4
+
5
+ **Let Claude Code edit in Instagram Edits for Mac, with the full editor and not just the home screen.**
6
+
7
+ [![CI](https://github.com/faisalkhanzemi/insta-edits-for-claude/actions/workflows/ci.yml/badge.svg)](https://github.com/faisalkhanzemi/insta-edits-for-claude/actions/workflows/ci.yml)
8
+ ![Python 3.9+](https://img.shields.io/badge/python-3.9%2B-blue)
9
+ ![Dependencies: none](https://img.shields.io/badge/dependencies-none-brightgreen)
10
+ [![License: MIT](https://img.shields.io/badge/license-MIT-lightgrey)](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/LICENSE)
11
+
12
+ <p align="center"><a href="https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/assets/hero.mp4"><img src="https://raw.githubusercontent.com/faisalkhanzemi/insta-edits-for-claude/main/assets/hero.gif" alt="A real Claude Code session making a beat-synced Dubai in 15 seconds reel inside Instagram Edits for Mac: clips cut on the beat, punch-in zooms, a speed ramp, a title and labels, frame checks, then export" width="100%"></a></p>
13
+
14
+ <p align="center"><sub>One prompt, a real Claude Code session, nothing scripted. Edits found no beats, so Claude analysed the music itself (122 BPM), cut every clip on a beat, checked its own frames and exported the reel. <a href="https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/assets/hero.mp4">Watch with sound</a>.</sub></p>
15
+
16
+ Edits for Mac, which Meta launched on 5 November 2026, has a built-in automation server that speaks MCP: in Meta's words, you can connect AI agents "to the desktop editor through MCP so they can help with your projects". You can point Claude Code at it directly, but you only get part of it.
17
+
18
+ Edits changes its tools with the screen. The home screen offers **32 tools**: projects, imports and catalogs. Open a project and it offers **274**, with text, captions, effects, transitions, keyframes, audio and export. Edits says it will announce that change (`tools.listChanged: true`) but never sends the notification. Claude keeps the 32 home tools for the whole session and never sees the editor.
19
+
20
+ This bridge sits between the two. After every tool call it asks Edits which tools it offers now. If the set has changed, it tells Claude, and Claude refreshes the list. It also fixes a reply format that some Claude Code builds reject, gives readable errors, and keeps your token out of config files.
21
+
22
+ ```
23
+ Claude Code ──stdio──▶ insta-edits ──HTTP──▶ Edits for Mac (127.0.0.1:19501)
24
+ ◀── tools/list_changed ──┘ checks the tool set after each call
25
+ ```
26
+
27
+ **Works with** Claude Code in the terminal and in the Code tab of the Claude desktop app. It's a standard stdio MCP server, so other MCP clients (the Claude desktop chat, Cursor, Codex) can run `insta-edits serve` too, though we've only tested Claude Code.
28
+
29
+ ## What you get
30
+
31
+ - **The full editor.** Claude receives `notifications/tools/list_changed` as soon as Edits moves between home (32 tools) and the editor (274). Without the bridge, that notification never arrives.
32
+ - **Replies that every Claude Code build accepts.** Edits marks each result `"resultType": "complete"` without the caching fields that newer MCP schemas pair with it. Some Claude Code builds then dropped every tool, with `Invalid result for tools/list: ttlMs … cacheScope`. The bridge removes the marker only when those fields are missing.
33
+ - **Your token stays private.** The plugin keeps it in the macOS keychain. The CLI keeps it in a `0600` file. It never appears in `~/.claude.json`, in logs or in error messages.
34
+ - **Errors you can act on.** "Cannot reach Edits: open it and enable the Automation Server" replaces a stack trace. A rejected token says how to update it.
35
+ - **`doctor` checks every link** from the app to the sign-in, and `--json` gives you a report to attach to a bug.
36
+ - **An `edits` skill** that teaches Claude how the server behaves: discover before guessing, work in normalised canvas coordinates, check rendered frames, and **never publish without your explicit go-ahead**.
37
+ - **Python standard library only.** Nothing to `pip install` for the plugin, and it runs on the `python3` that comes with macOS.
38
+
39
+ ## Requirements
40
+
41
+ - A Mac with Apple silicon (M1 or later) and [Edits for Mac](https://edits.instagram.com/desktop), free and signed in to Instagram
42
+ - Claude Code
43
+ - `python3` 3.9 or newer. Run `xcode-select --install` if macOS asks for the command line tools.
44
+
45
+ ## Install
46
+
47
+ ### 1. Turn on the automation server in Edits
48
+
49
+ Go to **Edits › Settings › Automation**, switch on **Enable Automation Server**, and copy the **Access token**. Keep Edits open while Claude works.
50
+
51
+ ### 2a. As a Claude Code plugin (recommended)
52
+
53
+ Start `claude` in a terminal and type:
54
+
55
+ ```
56
+ /plugin marketplace add faisalkhanzemi/insta-edits-for-claude
57
+ /plugin install insta-edits@insta-edits
58
+ ```
59
+
60
+ Claude Code asks for the access token with a masked prompt and stores it in your keychain. Restart Claude Code, then run `/mcp`: `edits` should show as connected. The plugin also installs the `edits` skill.
61
+
62
+ <details>
63
+ <summary>Installing from a shell script, or using the Claude desktop app</summary>
64
+
65
+ The shell commands do the same thing but don't prompt for the token, so set it afterwards with `/plugin configure insta-edits@insta-edits` inside Claude Code:
66
+
67
+ ```bash
68
+ claude plugin marketplace add faisalkhanzemi/insta-edits-for-claude
69
+ ```
70
+
71
+ ```bash
72
+ claude plugin install insta-edits@insta-edits
73
+ ```
74
+
75
+ A plugin installed this way, at user scope, also shows up in the Code tab of the Claude desktop app, which reads the same settings.
76
+ </details>
77
+
78
+ ### 2b. As a standalone MCP server
79
+
80
+ ```bash
81
+ pipx install git+https://github.com/faisalkhanzemi/insta-edits-for-claude
82
+ ```
83
+
84
+ ```bash
85
+ insta-edits set-token
86
+ ```
87
+
88
+ ```bash
89
+ claude mcp add --scope user edits -- insta-edits serve
90
+ ```
91
+
92
+ `set-token` asks for the token with a hidden prompt and saves it to `~/.config/insta-edits/token` with `0600` permissions. Never put the token itself on the `claude mcp add` line: it would end up in plain text in `~/.claude.json` and in your shell history.
93
+
94
+ ## Check the connection
95
+
96
+ ```bash
97
+ insta-edits doctor
98
+ ```
99
+
100
+ ```
101
+ insta-edits 0.1.0 doctor
102
+
103
+ ✓ macOS 27.0.1
104
+ ✓ Edits app installed /Applications/Edits.app
105
+ ✓ Automation server answering at http://127.0.0.1:19501/mcp (HTTP 403 without a token, as expected)
106
+ ✓ Access token from ~/.config/insta-edits/token
107
+ ✓ Sign-in metapilot-native 1.0.0, protocol 2025-06-18
108
+ ✓ Tools 32 on the current screen (home screen; Edits offers more once a project is open)
109
+ ✓ Reply format normalised for older Claude Code builds (resultType without caching fields)
110
+ ✓ Edits automation schema 2026.10.19-1
111
+ ✓ Tool-change notifications Edits announces them but never sends any; the bridge checks after each call and tells Claude
112
+
113
+ All good. Claude can drive Edits.
114
+ ```
115
+
116
+ Each `✗` line names its fix. Plugin users who want `doctor` can install the CLI as in 2b. The plugin token lives in the keychain, so without `set-token` the doctor checks stop at the sign-in step.
117
+
118
+ ## Using it
119
+
120
+ Ask for edits in plain words:
121
+
122
+ > Open my latest Edits project and tell me what's on the timeline.
123
+
124
+ > Import `~/Movies/broll/` into a new project, cut it to the beat of the voice-over, and add word-by-word captions in a clean sans.
125
+
126
+ > Add a soft zoom on every product close-up and a whoosh on each cut, then render a preview so I can check the frames.
127
+
128
+ Claude opens the project, the editor tools appear, and it works from them. It doesn't post. Publishing stays in the Edits window unless you explicitly tell Claude to share a specific video.
129
+
130
+ ## How it works
131
+
132
+ | Step | What happens |
133
+ | --- | --- |
134
+ | Session | The bridge forwards `initialize`, keeps Edits' `Mcp-Session-Id`, and sends `MCP-Protocol-Version` on every request. |
135
+ | Replies | It accepts both JSON and `text/event-stream` replies and batch requests, and normalises `resultType` only when the caching fields are missing. |
136
+ | Tool sync | After each `tools/call` it sends its own `tools/list` to Edits, using an id Claude never sees, and compares the tool names. If they changed, it writes `notifications/tools/list_changed` to Claude. Turn this off with `serve --no-sync`. |
137
+ | Notifications | If a future Edits build opens a server-to-client stream, the bridge listens on it and forwards what arrives. Edits doesn't offer one today, so the bridge stops trying after the first refusal. Turn it off with `serve --no-stream`. |
138
+ | Errors | When Edits is closed the bridge returns JSON-RPC `-32001`. When Edits returns an HTTP error it returns `-32002`. Both carry a one-line fix. |
139
+
140
+ Settings come from the environment: `EDITS_MCP_URL` (default `http://127.0.0.1:19501/mcp`), `EDITS_MCP_TOKEN`, and `EDITS_MCP_TOKEN_FILE`. Logs go to stderr.
141
+
142
+ ## Tested with
143
+
144
+ | | Version |
145
+ | --- | --- |
146
+ | Edits for Mac | 454.0.0 (server `metapilot-native` 1.0.0, automation schema 2026.10.19-1) |
147
+ | Claude Code | 2.1.296 |
148
+ | macOS | 27.0.1 |
149
+ | Python | 3.9.6 (system), 3.11, 3.13 in CI |
150
+
151
+ Edits updates often and its automation server is undocumented. If a new build breaks something, run `insta-edits doctor --json` and [open an issue](https://github.com/faisalkhanzemi/insta-edits-for-claude/issues/new/choose) with the output. It contains no token.
152
+
153
+ ## Troubleshooting
154
+
155
+ | Symptom | Fix |
156
+ | --- | --- |
157
+ | `Cannot reach Edits` | Open Edits and switch on Settings › Automation › Enable Automation Server. |
158
+ | HTTP 401 or 403 | The token changed in Edits. Update it in `/plugin`, or run `insta-edits set-token`. |
159
+ | Only home tools, even with a project open | Check that `edits` in `/mcp` points to the bridge and not straight at `127.0.0.1:19501`, and that you didn't start it with `--no-sync`. |
160
+ | Import fails with `file not found: ~/…` | Edits doesn't expand `~`. Pass the full path, such as `/Users/you/Movies/clip.mp4`. |
161
+ | Import fails with `Sandbox bookmark unavailable` | Edits is sandboxed. In our tests it imported from `~/Movies` and refused `~/Downloads`, `~/Desktop`, temp folders and project folders. Move the footage into `~/Movies` and import it from there. |
162
+ | Exported video is silent where the song should be | Songs from Edits' music library come in as licensed tracks, and exports started through automation leave them out: the music bed was silent in every test, while our own audio files exported fine. Export or post from the Edits window when a library song matters. |
163
+ | `addSongToComposition` adds a different song | Passing a track id sometimes added another track. Passing the exact title added the right song in our test. |
164
+
165
+ ## Security
166
+
167
+ - The bridge only connects to the URL you configure, which defaults to `127.0.0.1`. It sends nothing anywhere else and has no telemetry.
168
+ - The token is redacted in every log line, error message and `repr`. `doctor --json` reports where the token came from, never its value.
169
+ - Edits is signed in to your Instagram account. The bundled skill tells Claude never to publish, share or schedule without your explicit go-ahead for that specific post.
170
+ - Report vulnerabilities privately as described in [SECURITY.md](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/SECURITY.md).
171
+
172
+ ## FAQ
173
+
174
+ **How do I connect Claude to Instagram Edits?** Install Edits for Mac, switch on Settings › Automation › Enable Automation Server, then add this plugin with the two `/plugin` lines under [Install](#install). Claude can then open your projects and edit them.
175
+
176
+ **Can Claude edit Instagram Reels?** Yes, inside Edits for Mac. It can import clips, cut them on the beat, add captions, text, transitions, zooms and speed ramps, check rendered frames and export. You post the reel from Edits yourself.
177
+
178
+ **Does it work with claude.ai in the browser?** No. Edits runs on your Mac and only listens locally, so it needs Claude Code (or another MCP client) running on the same Mac.
179
+
180
+ **Is this official?** No. It's an independent open-source project, not affiliated with or endorsed by Meta, Instagram or Anthropic. "Instagram" and "Edits" are trademarks of Meta Platforms, Inc.
181
+
182
+ **Does it work on Windows or with the Edits phone app?** No. Edits on desktop is only available on macOS, and the automation server only exists there.
183
+
184
+ **Do I still need this if my Claude Code build accepts Edits' replies?** Yes, for the editor tools. Edits never announces that its tools changed, and no client can find that out without asking.
185
+
186
+ **Can Claude post to Instagram for me?** The bridge won't stop Claude from calling Edits' share tools, but the bundled skill tells it to wait for your explicit go-ahead. Posting from the Edits window is the safer default.
187
+
188
+ ## Development
189
+
190
+ ```bash
191
+ git clone https://github.com/faisalkhanzemi/insta-edits-for-claude && cd insta-edits-for-claude
192
+ python3 -m venv .venv && . .venv/bin/activate
193
+ pip install -e . pytest ruff
194
+ pytest && ruff check . && ruff format --check .
195
+ ```
196
+
197
+ The tests run against `tests/fake_edits.py`, a stand-in that behaves like the real server: it sends no notifications, changes its tool set when a project opens, and replies with `resultType`. You don't need a Mac or Edits to run them. See [CONTRIBUTING.md](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/CONTRIBUTING.md).
198
+
199
+ ## Credits
200
+
201
+ Demo footage: stock clips from [Pexels](https://www.pexels.com/license/) (Pexels License). Music: "Tech House vibes" by Alejandro Magaña, [Mixkit](https://mixkit.co/license/) (Mixkit License).
202
+
203
+ ## License
204
+
205
+ [MIT](https://github.com/faisalkhanzemi/insta-edits-for-claude/blob/main/LICENSE) © Faisal Khan
@@ -0,0 +1,15 @@
1
+ # Security
2
+
3
+ ## How the token is handled
4
+
5
+ - The Edits access token unlocks full control of the Edits app, which is signed in to an Instagram account. Treat it like a password.
6
+ - Installed as a Claude Code plugin, the token is entered in a masked prompt and kept in your system keychain.
7
+ - Installed manually, `insta-edits set-token` reads it from a hidden prompt and writes it to `~/.config/insta-edits/token` with `0600` permissions.
8
+ - The bridge never prints or logs the token, and `doctor --json` output contains no secrets, so it is safe to paste in an issue.
9
+ - The bridge only talks to the Edits server on your own machine (`127.0.0.1:19501` by default). It makes no other network requests and collects no telemetry.
10
+
11
+ If a token ends up somewhere public (a chat, a screenshot, a commit), regenerate it in Edits > Settings > Automation.
12
+
13
+ ## Reporting a vulnerability
14
+
15
+ Please report security issues privately through GitHub's **Report a vulnerability** button on the repository's Security tab rather than in a public issue. You'll get a reply within a few days.