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

# MCP Server

Let an AI agent drive MemoryString on your Mac through its local MCP server: setup, token, and what the tools can do.

Let an agent drive the open project: import, restyle, scrub, and 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…** (**⌘,**). It opens as a sheet on the main window. **Close** or Escape dismisses it (including after the sheet finishes closing).

![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-9cb297414567f9f7f6eaac6f5f2684cb0e936315%2Fmcp-settings.png?alt=media)

## Turn it on

1. Launch MemoryString.
2. Open **Settings…** (sheet on the main window).
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, or read the Help topics that ship with the app. It does not open this site.
* **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 Show menu → **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; Peek is UI-only) / **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. Finder / folder imports stay **linked**; **Photos.app** media is **copied** into Application Support **Imports** (no stable links into the Photos library). After a UI import, MemoryString may also prompt Keep Best when similar photo groups appear. 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. Import tools error while Long story short is running or a saved show is still opening (`canImportMedia` is false, same as greyed **Add**).
* **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**. Photos does not allow stable links into its database.
* **groups**: Photo Stack, Carousel, 3D Ribbon, Perspective Pair, Filmstrip, Scatter & Settle
* **transitions**: slide kinds, turn kinds on or off, shuffle cuts, pin / unpin group windows
* **style**: Looks, Energy (photo stills \~7.6s Calm / \~4.0s default / 2s Intense; opening card uses its own 7s / 6s / 4s curve; **Fit Show to Music** moves Energy), 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** (`set` / `set_background` / `clear_background` / **`set_closing`**: closing words on the existing end card, same as Titles → Closing; default text **The End**; ornament `none` / `line` / `diamond` / `flourish` / `ribbon`; Studio **lens** on the opening card) / **timing** (includes **auto\_trim**: same as context-menu **Auto Trim**: middle \~4 seconds plus up to \~1s toward a face; right about 70% of the time; no confirm; not on import; **`reset_video`** matches **Reset Video Duration**; undo with **document** `undo`) / **audio** (`import` / `remove` / `reorder` / `mute` / `volume` / `match_look` / **`fit_show_to_music`** / `mute_video` / mute noisy / mute all / unmute all) / **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, skips the opening card, 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**

About is not an MCP action. Use the **help** tool to read Help topics.

**get\_state** also reports `introLens`, closing words on the end card, per-clip `lensPins` (`null` = inherit the pool, `[]` = none), `isLoadingMusic`, `isFittingShowToMusic`, `matchLookSoundtrack` (Music Follows Show), `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`). If `isFittingShowToMusic` is true, wait until it is false, then retry Fit Show to Music.

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.

**Music Follows Show** (`match_look`) 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. **`fit_show_to_music`** moves Energy so the song covers the whole film, including the end card, then turns Music Follows Show off. If even Calm is too short or Intense is too long, it does nothing and returns why.

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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.memorystring.app/more/mcp.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.