> For the complete documentation index, see [llms.txt](https://memorystring.codebyz.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://memorystring.codebyz.com/more/mcp.md).

# MCP Server

Let an agent drive the open project — import, restyle, scrub, export — without clicking every pane. Works only **while the app is open**. Nothing listens until you enable it, and only on your Mac (`127.0.0.1`).

**MemoryString → Settings…** (**⌘,**).

![Enable MCP Server, Port, Copy Client Config, access token](https://316881897-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6lG8Zi4VdmddHJ8jUOT5%2Fuploads%2Fgit-blob-b355baacbbf5403805ec5119c828a5d629043c7a%2Fmcp-settings.png?alt=media)

## Turn it on

1. Launch MemoryString.
2. Open **Settings…**.
3. Turn on **Enable MCP Server**.
4. Click **Copy Client Config**.
5. Paste the snippet into Claude, Cursor, or a similar client as a Streamable HTTP server.

Closing MemoryString disconnects the client.

Default **Port** is **18765**. If status shows the port is already in use, pick another number.

## Token

The door key for every request. MemoryString creates a Bearer token on first launch so **Show** / **Copy** work even before you enable the server.

**Regenerate Token** replaces the secret (asks first) — existing client configs stop working until you paste the new snippet. Stored on your Mac (Application Support), not in the project file.

**MemoryString → Reset All Settings…** turns the MCP server **off**. The token file is kept.

## What the client can do

Call **get\_state** first. Then mutate the open project:

* **help** — list / search / read in-app Help (does not open the Help window)
* **document** — new, open, save, save as, close, delete, undo, redo. Untitled dirty work needs `save_first` (with a `path`) or `discard_unsaved`. **`open`** on a missing, unreadable, or damaged `.memorystring` (corrupt / broken JSON) does **not** silently land on Untitled — it returns `isError` with `show_state` (`missing` / `unreadable` / `damaged`), the same plain-English `title` / `body` the app would show, and `path`. Poll **get\_state** for `lastOpenFailure` after a failed open.
* **library** — import / remove / reorder / sort / shuffle / select / **keep\_best** (`confirm: true` required — same as Library **⋯** → **Keep Best Shots…**; extras move to Outtakes; videos are never Keep Best targets; undo with **document** `undo`) / **move\_to\_outtakes** / **move\_to\_takes** (same as the context menu; all given paths or the current selection) / **relink** (`path` or `clip_id` plus `new_path` — point a broken Finder link at the file on disk; no picker). Same ingest as **Add / +**, Finder drop (files or a folder), Photos.app drag, and paste. After a UI import, MemoryString may also prompt Keep Best when similar photo groups appear. Finder / folder imports stay **linked**; **Photos.app** media is **copied** into Application Support **Imports**. If a linked photo later moves, `get_state` lists it under `missingMedia` and the clip’s `missing` flag; **relink** (or pass the correct `new_path`) repairs it.
* **photos** — `list_albums`, `import_album` (title match), or `import_recent` (`Last 7 Days` / `Last 30 Days` / `Last Year`) without opening the sheet (same ingest as **File → Import from Photos…**; needs Photos access). Those imports are **copies** into Application Support **Imports**.
* **groups** — Photo Stack, Carousel, Ribbon, Perspective Pair, Filmstrip, Scatter & Settle
* **transitions** — slide kinds, mix, shuffle cuts, pin / unpin group windows
* **style** — Looks, Energy (photo stills \~7.6s Calm / \~3.4s default / 2s Intense; intro uses its own 7s / 6s / 4s curve), Photo Size, stage, customize knobs (including Anamorphic Streaks and Refract Bubbles knobs and presets), **atmosphere** (`none` / `bubbles` / `leaves`) and **decals** (`none` / `travel` / `vacation` / `party` / `florals` / `wedding` / `pets` / `sports`) as single-choice menus, and **clip\_lens** (Studio per-slide Lens Effect hand picks; consecutive Refract Bubbles pins share one field; empty `effects` = deliberate **None**; `remove_all` = **Use automatic** — the slide rejoins the shared deal and an effect may reappear). Look / Shuffle re-deal automatic slides only; hand picks including None stay until cleared; pool checkboxes and How often govern automatic slides only
* **media\_edit** — rotate (`cw` / `right` = Clockwise, `ccw` / `left` = Counter Clockwise), flip, [center of interest](/build-your-movie/preview.md#center-of-interest) (original files are never rewritten)
* **captions** / **intro** (including Studio **lens** on the opening card) / **timing** (includes **auto\_trim** — same as context-menu **Auto Trim**: middle four seconds plus up to 1s toward a face; best-effort, not guaranteed; no confirm; not on import; **`reset_video`** matches **Reset Video Duration**; undo with **document** `undo`) / **audio** (`import` / `remove` / `reorder` / `mute` / `volume` / `match_look` / `mute_video`) / **output**
* **export\_movie** — `export` writes an MP4 to a path you pass (no save panel, no Finder bounce); `cancel` stops an in-flight encode. Optional `quality` (`low` / `medium` / `high` / `maximum` → Compact / Share / High / Best; **Share** / `medium` default), `quality_level` (0…1), `resolution` (`1080p` / `4k`; not available for Cinema 21:9; rarely refuses `4k` if the Mac is short of free memory — close other apps or use `1080p`), `fps`, `format`, `social_safe`, **`screensaver`** (same as the Export Movie **Screensaver** checkbox — no audio, skip intro, Stage-color loop, no end credit)
* **playback** — play, pause, seek, next / previous slide, **start** (go to start), **warm\_now** (dirty preview segments only, non-blocking), **stop\_warming**

Help and About windows are not exposed as UI; use the **help** tool to read topics.

**get\_state** also reports `introLens`, per-clip `lensPins` (`null` = inherit the pool, `[]` = none), `isLoadingMusic`, `matchLookSoundtrack`, `untitledNeedsSave`, `playlistIsPristineAutoManaged`, `previewAudioMuted`, `isExporting` / `exportProgress`, and smooth-play warm readiness: `canWarmNow`, `isWarming`, `warmStatus` (transport pill text, e.g. `Warming 3/12`), and `autoWarmOnPlay` (always `true` — both modes auto-warm on Play). Poll `get_state` after **warm\_now** until `isWarming` is false and `canWarmNow` is false. **warm\_now** is a no-op when every segment is already warm or a warm is already running (`reason`: `already_warm` / `already_warming`).

Broken links and bad show files: each clip and playlist row has `missing` (true when the original file is gone or unreadable). `missingMedia` lists every broken path with `role` (`clip` / `outtake` / `playlist` / `intro_background`), `filename`, and `clipId` when it is on the show. `missingMediaCount` is the size of that list. A failed **document** `open` also sets `lastOpenFailure` (`kind` / `title` / `body` / `path`) so the agent can tell a damaged show from an empty one.

**Match Look Soundtrack** is on by default (same as the app). After the first photos land it soft-seeds mood music from that Look’s pool; a Look click retargets that bed while it is still untouched. `audio.import` replaces that auto bed, same as a Finder drop. Soundtrack edits (**import** / **remove** / **reorder** / **mute** / **volume** / music trim) error while `isLoadingMusic` is true — poll **get\_state** and retry. Turn **match\_look** off *before* importing photos or applying a Look if you want silence or only your files.

Pick New Music, Extend to Fill, and Surprise me live on the Audio tab in the app — they are not MCP actions.

Destructive **delete** requires `confirm: true`. Untitled dirty work is not thrown away unless you pass `save_first` (with a `path`) or `discard_unsaved` — the agent has to mean it.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://memorystring.codebyz.com/more/mcp.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.