Aspects MCP
Aspects ships an MCP server inside the app bundle. It gives an assistant like Claude Code read access to your library, and, if you switch it on, the ability to act on it. This page is the reference. Assistants is the shorter introduction.
Connecting
One command. Settings ▸ Assistants shows the exact path for your install, with a button to copy it, because the helper lives inside the app and the app is not always in /Applications.
claude mcp add aspects -- <path to Aspects.app>/Contents/Helpers/aspects-mcp
There is also a double-click installer for Claude Desktop. It carries a small shim that finds your installed copy at launch rather than a second copy of the binary, so updating Aspects updates the server.
Two tiers, and only one needs permission
Reading goes straight to the library's files. It works with Aspects closed and needs no permission at all. Nothing about your library leaves your Mac: the server runs on your machine and talks to the client over standard input and output.
Acting needs the app. The server never writes anything itself. It asks Aspects to perform the change through the same code a click goes through, over a loopback socket with a fresh token each launch, so an edit made by an assistant behaves exactly like one you made. That needs Aspects open and “Let assistants act on this library” switched on in Settings ▸ Assistants. It is off until you turn it on.
Reading
library_overview- Counts and folders. The cheap way to orient before listing anything.
list_documents- Artboards, decks and notes, newest first. Filter by kind, folder, name or date.
get_document- One document in full. A note returns its whole text; a deck returns its slides, its fonts and whether it is shared.
search- A word anywhere: names, note bodies, every slide of every deck, and a Capture artboard's page. Case and accent insensitive.
list_sources- The pictures and clips that went into the work, with dimensions, orientation, ratio, duration, codec, colour profile and whether each reads as greyscale.
list_exports- Files Aspects has rendered, with their paths on disk.
find_assets- Final assets, searched by the names you gave them.
storage_report- What the library weighs and how much of it is the same bytes twice.
design_system- The grids, deck grids, themes and slide types you have saved and reuse.
Acting
open_document- Opens a document in Aspects.
preview_document- A picture of a document, as a PNG you can read. An artboard hands back its thumbnail; a deck renders its first slide.
export_artboard- Renders an artboard with the settings it already has.
export_status- Where a render has got to, and the path once it is done.
create_document- Makes a note or an artboard.
update_document- A name, a note's text, an artboard's page, and an artboard's output shape and width.
delete_document- Removes a document. Needs a second switch, and takes two calls.
open_documents- Which documents you have open right now.
quick_utility- One of the small utilities. Answers in place where it can; opens the tool in front of you where the result is a file.
Deleting
Deleting has a switch of its own, nested under the first and also off by default, because nothing in Aspects undoes one: the document, its thumbnail and its copied sources go, and ⌘Z is editor state rather than a library operation.
It also takes two calls. The first is refused and tells the assistant exactly which document would go, so it has to name it to you and get an answer before the second. A refusal that mentions the switch means the setting, not a fault.
Settings ▸ Assistants lists the last two hundred acts an assistant has taken, newest first. It is a record rather than an undo.
Resources
Beyond tools, the server offers documents as attachable resources, so you can hand an assistant the note you mean rather than having it go looking. Notes, artboards and decks are at aspects://note/<id> and the equivalents.
Four short guides sit alongside them at aspects://guide/<name>: what the nine tools are and which to reach for, Capture's three modes and which one is deterministic, how the library is organised, and what the server will not do. There is also aspects://activity, the same record Settings shows.
Prompts
Two, and they appear in a client as slash commands. weekly_review summarises what you worked on and what you rendered, which are two different questions and a summary of only the first misses the output. find_deliverable locates a finished file by what it shows rather than what it is called.
What it will not do
The server writes nothing. Reads come from the library's files and every change is performed by the app, which is what keeps one writer per store.
It returns no file paths from outside the library. Sources can be folders you pointed Aspects at anywhere on disk, so list_sources answers with what a file IS, its dimensions, duration, colour and original filename, and never with where it came from.
Most of an artboard cannot be adjusted. A name, a page, an output shape and an output width, and that is deliberate: margins, placement, zoom and effects are set by eye while watching the stage, and a list of ninety dials would invite an assistant to try.
Nothing an assistant does changes how a render comes out beyond those fields. Frame 400 is the same frame 400 on any Mac and on any run, which is the premise the whole renderer rests on.
Protocol
The server speaks MCP 2026-07-28 and the three revisions before it, and answers with the newest one it genuinely implements rather than echoing whatever a client asks for. It implements server/discover, carries a result type on every result, and sends cache hints on listings. It issues no server-initiated requests, declares no subscriptions, and implements neither sampling, roots nor logging, all three of which that revision deprecates.
If it is not working
Run the helper with --probe. It prints what the server can see and exits, which separates “the library is empty” from “I cannot reach it” in one step. Settings ▸ Assistants also shows whether the service is listening and on which port.
