Edits MCP Bridge

An independent, local MCP server that bridges stdio MCP clients to the Automation MCP endpoint built into Edits. It discovers Edits' actual tools and schemas rather than inventing an editing API.

Live verified: authenticated discovery of 274 native tools, plus project creation, media import, trim, split, text overlay, save/reopen, and video export on Edits 454.0.0. Tool availability varies by app version and screen; discovery does not mean every tool was tested. See the acceptance report →

This is a community project, not a Meta or Instagram product. Edits must be installed separately. The bridge does not provide an editor, cloud rendering, or an Instagram scraping API.

Why this bridge?

Related MCP server: Rendley MCP

How it connects

flowchart LR
    A[Your MCP client] -->|stdio| B[Edits MCP Bridge]
    B --> C{Allowlist + write gate + schema}
    C -->|Authenticated loopback HTTP| D[Edits native MCP]
    D --> E[Your editing timeline]

See inspected native editing recipes →

Live demo

Actual output from a dedicated test project: a six-second generated clip was trimmed to five seconds, split into two timeline clips, overlaid with text and exported through MCP. The file was independently probed and fully decoded: 5.000 s · 2560×1440 · 30 fps · HEVC + AAC. The demo contains only generated test media.

Quick start

1. Install

Requirements: macOS with Edits, Node.js 22+, npm and /usr/bin/python3 for the local diagnostic tool.

git clone https://github.com/vizyonajans/edits-mcp.git
cd edits-mcp
npm ci --ignore-scripts
npm run smoke

The local smoke test starts the stdio server and discovers the bridge tools. It does not modify Edits or require a token.

2. Enable Edits Automation

In Edits, open Settings → Automation, enable Automation Server and copy the access token. Use the endpoint displayed by your installed app. The observed default is:

http://127.0.0.1:19501/mcp

Save the token privately from an interactive Terminal:

mkdir -p "$HOME/.config/edits-mcp"
chmod 700 "$HOME/.config/edits-mcp"
python3 scripts/save-token.py "$HOME/.config/edits-mcp/access.token"

The saver hides the input, creates a private 0600 file and refuses to overwrite an existing file. Do not put the token in this repository, chat, a GitHub issue, or a command-line argument.

3. Add your MCP client

Use your client's stdio MCP configuration. Replace the three absolute paths below. command -v node shows the Node executable path.

{
  "mcpServers": {
    "edits-local": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/edits-mcp/src/server.mjs"],
      "env": {
        "EDITS_MCP_URL": "http://127.0.0.1:19501/mcp",
        "EDITS_TOKEN_FILE": "/absolute/private/path/access.token",
        "EDITS_ALLOWED_TOOLS": "[]",
        "EDITS_ALLOW_WRITES": "0"
      }
    }
  }
}

Restart the client, call edits_status, then edits_catalog. A complete example is in examples/mcp.json. GUI clients may not inherit your Terminal PATH, so use absolute paths.

4. Allow only the tools you need

Start with inspected, read-only tools from your current native catalog:

{
  "EDITS_ALLOWED_TOOLS": "[\"state\",\"clips\"]",
  "EDITS_ALLOW_WRITES": "0"
}

Then call:

{
  "name": "edits_invoke",
  "arguments": {
    "name": "state",
    "arguments": {}
  }
}

For editing, add the exact tools you reviewed and explicitly set EDITS_ALLOW_WRITES to "1". Never add tools you do not understand. A native tool may export, delete, publish or access files; an allowlist entry grants that tool's actual capabilities.

Important: macOS file access

Edits' own sandbox still applies. A path string is not a file-access grant. The live test initially received a native sandbox-bookmark error. Selecting the generated video through Edits → File → Import Media granted access; the subsequent MCP import succeeded.

Export to a directory Edits can access. An arbitrary output directory was denied in the test; the export folder established by Edits' own export flow worked. Always poll exportStatus and verify the output file: export returning ok: true means the job was accepted, not that encoding completed.

No Accessibility, Apple Events or Screen Recording permission is required by this bridge. Other Edits features may have their own OS permissions. Do not disable macOS protections to make a call work.

Bridge tools

The native catalog can change between the home and editor screens. Every invocation refreshes it before authorization and dispatch.

Configuration

The default configuration allows catalog discovery, but no native tool invocation. Read-only native tools also require an allowlist entry and a trustworthy readOnlyHint when the write gate is closed. Annotations are hints, not a safety guarantee.

The bridge limits native catalogs to 2000 tools/100 pages, the request queue to 32 calls, HTTP responses to 8 MiB, serialized argument length to 1 MiB and schema length to 256 KiB. JSON string lengths use JavaScript string units. Supported structural schema dialects are draft-07 and draft-2020-12; format annotations are not enforced.

A timeout or cancellation does not roll back an edit. Inspect Edits before retrying. The bridge never automatically replays a native editing call. Read the full security model →

Test it yourself

The GitHub Actions matrix has passed on macOS 15 / Ubuntu 24.04 with Node 22 / 24. View the workflow and current results →

npm test
npm run test:coverage
npm run test:python
npm run smoke

For authenticated, read-only discovery against your running app:

EDITS_TOKEN_FILE=/absolute/private/path/access.token npm run smoke:live

This script discovers the catalog without invoking native editing tools. More detail: automated test report, live acceptance evidence, and sanitized results.

Troubleshooting

Privacy

This repository contains no access tokens, personal email addresses, home-directory paths, private project data or machine-specific diagnostic reports. Its demo is synthetic. The bridge has no telemetry and sends authenticated requests only to the configured loopback endpoint. Local diagnostic outputs are for your MCP client and should not be pasted publicly without review. Privacy and publication policy →

Contributing

Bug reports, compatibility reports and small, well-tested improvements are welcome. Read CONTRIBUTING.md before opening a pull request. Include whether a result came from a fixture or the actual Edits app. Never post tokens or private media.

If this helps your workflow, a star makes it easier for other creators and developers to discover the project.

Contact and license

• Questions and bugs: GitHub Issues

• Professional enquiries and private security reports: info@vizyoncreative.com

• MIT License

Edits and Instagram are trademarks of their respective owners. This project is independent and is not endorsed by Meta or Instagram.