LocalScribeMac · power users
AI assistants (MCP)
LocalScribe for Mac includes a local Model Context Protocol server. Any assistant that speaks MCP — Claude Code, Claude Desktop, Codex, ChatGPT for Mac and others — can read your notes, tags, analysis and learning dictionary while LocalScribe is running, and, only if you allow it, make changes.
Nothing leaves your Mac. The assistant talks to a tiny helper inside the app bundle, which relays requests to LocalScribe over a local socket. No network port, no upload, and read-only until you say otherwise.
How it works
- The app bundle ships a helper,
localscribe-mcp, insideLocalScribe.app/Contents/MacOS. Your client runs it as the MCP server. - The helper speaks stdio to the client and relays every request to LocalScribe over a Unix socket in the app’s group container.
- If LocalScribe isn’t running, the helper launches it. The session ends when you quit LocalScribe.
- Connections are read-only by default. Writes need the “Allow assistants to make changes” switch in Settings and the
--allow-writeflag on that connection. - Everything an assistant changes is listed under Settings → AI Assistants → Recent changes, labeled with the client name.
Requirements: LocalScribe for Mac 1.3 or later, macOS 15 or later, and an MCP client on the same Mac.
Set up a client
Open LocalScribe → Settings → AI Assistants, pick your client and press Copy: the snippet already contains the right path to the helper. The examples below assume LocalScribe lives in /Applications.
Paste in Terminal. Registers LocalScribe for every project (user scope); use --scope project to limit it.
claude mcp add --scope user --transport stdio localscribe -- "/Applications/LocalScribe.app/Contents/MacOS/localscribe-mcp" --client "Claude Code"If you move LocalScribe to another folder, run the command again with the new path.
Helper flags
| Flag | Meaning |
|---|---|
--client NAME | Label shown in LocalScribe's activity log and the “Connected now” list. |
--allow-write | Let this connection create, edit, tag and delete. Also needs the switch in Settings. |
--no-launch | Fail instead of launching LocalScribe when it isn't running. |
--timeout SECONDS | How long to wait for LocalScribe to start listening (default 25). |
--diagnose | Print where the socket should be and whether the app is reachable. |
Permissions
| Read | Write | |
|---|---|---|
| Settings → “Allow assistants to make changes” | not needed | required |
--allow-write on the connection | not needed | required |
| Deleting a note or a tag | — | also needs confirm: true, which assistants only send after you agree in the conversation |
Turn the switch off at any time to make every connection read-only immediately. Turn off “Enable AI assistant connections” to stop the server entirely.
What assistants can see
Resources
| URI | Contents |
|---|---|
localscribe://notes | The 50 most recent notes (id, title, date, tags, category, preview) as JSON. |
localscribe://today | Every note captured today, as one Markdown document. |
localscribe://current | The note open in the editor, as Markdown. |
localscribe://pending | Every active note still marked pending — the queue — as one Markdown document (newest first, max 50). |
localscribe://tags | All tags with note counts and the keywords that make the tag suggester propose them. |
localscribe://categories | Classification categories used by the on-device analysis. |
localscribe://dictionary | Confirmed transcription corrections and ignored tokens. |
localscribe://stats | Capture volume, streak, top tags, categories and topics. |
Read tools
| Tool | What it does |
|---|---|
localscribe_list_notes | Newest-first list with id, title, date, duration, tags, status, category and preview. Filter by text, tag, status (pending, later, done), category, period (today, yesterday, week, month, all) or ISO dates; sort (including by status) and page. |
localscribe_get_note | One note in full as Markdown (default), JSON (every field, optional timestamped segments) or bare text. latest: true returns the most recent note. |
localscribe_search_notes | Full-text search; every word must appear. Returns a snippet around the first hit. |
localscribe_get_current_note | The note open in the editor plus what the app is doing (idle, recording, transcribing). |
localscribe_export_notes | Several notes as one Markdown document with front matter, picked by ids, tag or period. |
localscribe_list_tags | Tags with color, quick-tag flag, note count and keywords — the words that make LocalScribe suggest each tag. |
localscribe_suggest_tags | What the on-device tag suggester would propose for a note or any text: keyword matches with the reason, plus Apple Intelligence's picks when available. Applies nothing. |
localscribe_list_categories | Category keys, labels and descriptions. |
localscribe_list_dictionary | Confirmed corrections (wrong → right) and ignored tokens. |
localscribe_list_suspect_words | Words the transcription probably got wrong, aggregated across notes with counts and suggestions. |
localscribe_get_stats | Notes, words and minutes for today, 7 days, 30 days and all time; streak; top tags, categories, urgency, topics, languages and busiest hours. |
localscribe_open_note | Bring LocalScribe forward with a note open. Changes nothing. |
Write tools (need write access)
| Tool | What it does |
|---|---|
localscribe_create_note | Create a text note (a summary, minutes, a cleaned-up dictation). Labeled as assistant-written and analyzed on-device like any other note. |
localscribe_update_note | Change title, text, status, pinned or archived. Replacing text counts as a hand edit and triggers re-analysis. The note open in the editor cannot have its text replaced. |
localscribe_set_note_status | Mark one or several notes pending, later or done — done after you've acted on them, so the queue stays true. |
localscribe_set_note_tags | Add or remove tags on one or several notes; missing tags are created. |
localscribe_create_tag | Create a tag, optionally with one of the app's eight colors. |
localscribe_set_tag_keywords | Teach the tag suggester: add, remove or replace the keywords (project names, people, codenames, abbreviations, any language) that make a tag match. |
localscribe_delete_tag | Delete a tag everywhere. Requires confirm: true. |
localscribe_add_dictionary_rule | Confirm a correction: future notes get wrong replaced by right, and right is fed to the speech engines as vocabulary. |
localscribe_remove_dictionary_rule | Delete a rule by its wrong token. |
localscribe_set_note_analysis | Write summary, topic, urgency, category, entities and actions — the same layer Apple Intelligence fills. Never touches the text. |
localscribe_reanalyze_note | Re-run the on-device analysis for one note, or start a background pass over pending or outdated notes. |
localscribe_delete_note | Permanently delete a note and its recording. Requires confirm: true. Prefer archiving. |
Prompts
| Prompt | Use |
|---|---|
daily_review | Summarize a day's notes, extract action items and suggest tags. |
work_the_queue | Go through every pending note, do or draft what each one asks, and mark them done after you confirm. |
teach_tags | Find the words you actually say for each project and propose them as tag keywords. |
propose_dictionary | Turn aggregated suspect words into proposed correction rules. |
mind_map | Build a conceptual mind map from a note or a period (pairs well with the MindNode MCP). |
tidy_tags | Find duplicate, near-duplicate and unused tags and propose a cleanup. |
Things to try
- “What did I capture today? Group it by topic and list the action items.”
- “Read everything still pending, do what you can, and mark those notes done.”
- “Which words do I keep saying for the Walter project? Add them as keywords of that tag.”
- “Search my notes for the launch plan and give me a timeline.”
- “Look at the suspect words and propose dictionary rules. Don't add any until I say so.”
- “Take the note I have open and write a clean summary as a new note tagged “summary”.”
- “Which tags are near-duplicates? Suggest merges.”
Troubleshooting
- claude: command not found. Usually a PATH problem rather than a missing install. The CLI lives in ~/.local/bin, which your shell only sees if a profile puts it there — check with ls ~/.local/bin/claude, and if it exists add export PATH="$HOME/.local/bin:$PATH" to ~/.zshrc, then open a new Terminal. If it really isn't installed, use the Claude Desktop JSON config instead.
- The client can't connect. Run the helper with --diagnose in Terminal. It prints the socket path and whether LocalScribe is reachable. Check that “Enable AI assistant connections” is on in Settings → AI Assistants.
- A write was refused. Both the Settings switch and --allow-write must be on for that connection. The text of the note currently open in the editor is never replaced; close it or switch notes first.
- My analysis was overwritten. After a text replacement LocalScribe re-analyzes the note in the background. Set the analysis before the text, or wait a few seconds.
- I moved the app. Register the client again with the new path. The Settings pane always shows the current one.
Questions
Something missing from this page? Write to us from the Support page. How LocalScribe handles data is described in the Privacy policy.