Using MCP with Outerline

Overview

Outerline for Mac includes built-in MCP support so AI tools can work directly with your notes.

That means Claude Code, Codex, and other MCP-compatible tools can:

• Read notes from your library
• Search across your documents
• Inspect outlines, backlinks, links, tags, annotations, and graph data
• Read and create selected-text comments, with stable links back to the commented passage
• Set or clear custom document display titles, and manage tags, tag colors, and stars
• Generate outerline:// deep links to documents, headings, lines, and annotations
• Resolve pasted outerline:// links back to their current note or folder target
• List folders and find the right destination folder before creating or moving notes
• Create empty folders and missing parents with create_folder
• Rename or move a folder, or both, with edit_folder, preserving its contents and stable links
• Create notes, rename or move notes and folders, append to them, replace sections, or rewrite a whole note with edit_document
• Browse, diff, search, and restore version history snapshots
• Work with the note and text selection you currently have open in Outerline

The goal is simple: let agents work with your notes in a structured, Outerline-aware way instead of treating your library like an unorganized folder of files.

Creating and Editing Folders

Use create_folder with a relative path, such as Projects/2026/Ideas. Missing parents are created automatically. Existing folders succeed without changing their identity; a file at the requested path causes an error.

Use edit_folder with fromPath and toPath to rename, move, or do both. For example, change Projects/Ideas to Archive/Research. The destination includes the folder name, and its parent must exist; create it first if needed. Contents and UUID-based links are preserved. Existing destinations are never overwritten or merged. An unchanged valid folder path succeeds without changes; vault-root edits and moves into descendants are rejected.

Tool change: edit_folder replaces rename_folder and move_folder. Update saved workflows to use the new name with the same fromPath and toPath inputs, then reconnect your MCP client after updating Outerline.

Before You Start

Make sure:

1. Outerline is installed in /Applications/Outerline.app
2. You have opened Outerline at least once
3. You already have a library set up in Outerline

If you want to use tools that read or edit the current selection, keep Outerline open while you work.

The MCP Bridge Toggle

Outerline’s MCP bridge is controlled by Outerline > Settings > General > MCP Bridge (“Allows agents to use Outerline tools”), and it is on by default. If an agent cannot see your library, check this first.

Changing the toggle does not affect sessions that are already open. After enabling it, reconnect any apps or integrations before they can use Outerline tools; after disabling it, restart any existing services to fully close open sessions.

Storage Locations

Outerline MCP follows the library location you choose in Outerline.

• In the Mac App Store version, the built-in iCloud library is discovered automatically after you open Outerline once.
• If you choose your own library folder, Outerline MCP uses that folder. When that folder lives in iCloud Drive, Dropbox, or another sync provider, sync timing is controlled by that provider.
• Live editor tools such as get_active_document, get_selection, insert_at_cursor, and replace_selection require Outerline to be running.

Setup

Claude Code

claude mcp add outerline /Applications/Outerline.app/Contents/Resources/OuterlineMCP -- --stdio

After that, Claude Code should be able to discover Outerline and use its tools automatically.

Codex

codex mcp add outerline -- /Applications/Outerline.app/Contents/Resources/OuterlineMCP --stdio

After that, Codex should be able to discover the outerline server and call its tools directly.

Example Workflows

Once connected, you can ask an agent to perform everything from simple lookups to complex multi-step tasks across your library.

Simple Actions

• "In Outerline, find notes mentioning 'TestFlight'."
• "In Outerline, what notes link to this document?"
• "In Outerline, list all notes in Projects/Launch."
• "In Outerline, create a new note in Ideas/ with this draft."
• "In Outerline, rename Ideas/Draft.md and move it into Projects/Launch/."
• "In Outerline, resolve this deep link and tell me which note it points at."
• "In Outerline, find the Plan folder before you create this note."
• "In Outerline, add a comment to the selected sentence in this note."
• "In Outerline, rewrite my current selection."

Advanced Workflows

Combine multiple tools for powerful automation and research:

The "Weekly Recap"

Prompt: "In Outerline, look at my notes from the last 7 days, find anything tagged #meeting, and create a 'Weekly Sync Summary' note in the Archive/ folder."

Uses: vault://recent, get_document, create_document

The "Deep Research"

Prompt: "In Outerline, search for 'Project Phoenix' across all notes, find the most mentioned person, and show me all backlinks to their profile note."

Uses: search_documents, get_backlinks

The "Context-Aware Editor"

Prompt: "In Outerline, look at what I have selected, find related notes in my library that mention these terms, and insert a 'Related Reading' section at my cursor."

Uses: get_selection, search_documents, insert_at_cursor

The "Ghostwriter"

Prompt: "In Outerline, look at my last 5 notes tagged #writing-style, then rewrite my current selection to match that same tone and formatting style."

Uses: list_documents, get_document, get_selection, replace_selection

The "Conflict Resolver"

Prompt: "In Outerline, I'm drafting a new project plan in Projects/2026/. Compare this draft against my 'Product Strategy' and 'Technical Constraints' notes. Are there any contradictions or missed requirements?"

Uses: get_active_document, get_document

The "Cross-Linker"

Prompt: "In Outerline, get a deep link to the 'Requirements' heading in my current note and create a Linear issue that links back to it."

Uses: get_active_document, get_deep_link, plus an external tool like Linear MCP

The "Visualizer"

Prompt: "In Outerline, look at the backlinks for 'User Authentication' and create a Mermaid sequence diagram in a new note called 'Auth Flow' that shows how all these notes interact."

Uses: get_backlinks, get_links, get_document, create_document

The "Content Archaeologist"

Prompt: "In Outerline, I cut a paragraph about onboarding from my 'Product Strategy' note sometime last week. Can you find it and show me what I removed?"

Uses: find_deleted_content, diff_versions

The "Writing Progress Report"

Prompt: "In Outerline, show me how my 'Chapter 3' note has grown over time. When were my biggest writing sessions?"

Uses: get_writing_timeline

Tools

Outerline MCP tools fall into three groups.

Read Tools

These help an agent explore and understand your library. They usually work even if Outerline is not running.

list_documents

Lists notes in your library. Optional filters: folder, tag, starred.

Useful for exploring a folder, finding tagged notes, or asking for starred notes.

get_document

Reads the full content of a note. Look it up by relative path or UUID.

Useful for loading a known note or following a stable document link.

search_documents

Full-text search across your library by query.

Useful for finding notes by phrase or locating context before editing.

get_outline

Returns the heading structure of a note.

Useful for quickly understanding a long note, navigating to the right section, or deciding where new content belongs.

get_backlinks

Finds notes that link to the target note via wiki links.

Useful for seeing what references a note and checking related context.

get_links

Returns the links inside a note — wiki links and external links.

Useful for seeing what a note points to and understanding note relationships.

get_annotations

Returns highlights, highlight notes, and selected-text comments for a document.

Useful for reviewing highlighted passages or finding notes attached to exact text.

list_comments

Lists selected-text comments for a document, including each comment body, selected text, ID, creation time, and a stable annotation deep link.

Comments live in Outerline's metadata sidecar and do not change the Markdown file. They remain available for review even when the original selected text no longer resolves.

get_tags

Returns tags for one note, or all tags across the library with document counts.

Useful for reviewing a note's tags or understanding tag usage across the vault.

get_tag_colors

Returns all tag color assignments in the vault without changing any documents.

get_graph

Returns graph information for one note and its neighbors, or the full library.

Useful for exploring connected notes or understanding local context around a document.

get_deep_link

Generates an outerline:// deep link URL. Identify the target by path or uuid. Optionally target a specific location with line, heading, or annotation. Set folder to true for folder links.

Useful for embedding stable links in external tools (Linear issues, Slack messages, scripts), cross-referencing between Outerline and other systems, or building automation that links back to specific passages.

resolve_deep_link

Resolves an outerline:// URL to its concrete document or folder target without opening it. Input: url.

Useful when a user pastes a deep link into an agent session and the agent needs the concrete note or folder path before reading, editing, or moving related content.

list_folders

Lists folders in the vault as flat JSON entries. Optional inputs: root, depth.

Useful when an agent needs the exact destination path before creating or moving a note.

find_folder

Finds folders by exact or substring match against folder names and paths. Input: query.

Useful for resolving natural-language requests like "put this in Plan" without scanning the full vault tree first.

Write Tools

These help an agent create or update notes. If Outerline is running, changes will refresh in the app.

create_document

Creates a new markdown note. Inputs: path, content.

Useful for new notes, drafts, or templates.

rename_document

Renames a note in place without changing its folder. Inputs: fromPath, toPath.

Useful when a note title changes but it should stay in the same location.

move_document

Moves a note to a different folder. Inputs: fromPath, toPath.

Useful when reorganizing documents into a new section of the library.

create_folder

Creates an empty folder and missing parents. Input: path. Existing folders keep their UUIDs; file collisions fail.

Example: {"path": "Projects/2026/Ideas"}.

edit_folder

Renames or moves a folder, or both. Inputs: fromPath, toPath. The complete destination path includes the folder name, and its parent must exist. Contents and UUIDs are preserved; existing destinations are never overwritten or merged.

Example: {"fromPath": "Projects/Ideas", "toPath": "Archive/Research"}.

append_to_document

Adds content to the end of a note. Inputs: path, content.

Useful for journals, meeting notes, logs, and ongoing notes.

replace_section

Replaces the content under a heading. Inputs: path, heading, content. Heading matching is case-insensitive.

Useful for updating one section without rewriting the whole note, or refreshing summaries, plans, or status sections.

edit_document

Replaces the entire content of a document. Inputs: path, content.

Any tags on the original document are preserved automatically, even if the new content doesn't include them.

Useful for full rewrites, restructuring a note, or regenerating content from scratch without losing tag metadata.

edit_document_title

Sets or clears a custom display title without renaming the Markdown file. Provide title plus exactly one of path or uuid. Whitespace-only titles clear the customization and restore the generated title.

create_comment

Adds a nonblank comment body to an exact selected_text match without changing the Markdown file. When the text repeats, optional approximate_offset selects the nearest UTF-16 occurrence. Each document supports up to 500 comments; invalid or over-cap writes are rejected without mutation.

create_annotation

Adds a highlight or annotation to a document. Inputs: path, highlighted_text, optional color, optional note.

Supported colors: yellow, blue (cyan), green, pink, purple.

Useful for marking passages or saving notes on exact text.

set_tags

Adds tags to a note. Tags already present are skipped. Inputs: path, tags.

Useful for tagging notes, normalizing tags, or organizing a note after writing.

rename_tag

Renames a tag across every document in the library. Inputs: old_tag, new_tag.

Tags inside code blocks, inline code, URLs, and headings are left untouched. If a document already contains the new tag, it is skipped to avoid duplicates. Any assigned tag color is migrated to the new name.

Useful for normalizing tag names, fixing typos, or consolidating related tags.

delete_tag

Removes a tag from every document in the library. Input: tag.

Tags inside code blocks, inline code, URLs, and headings are left untouched. Cleans up whitespace left behind by removal.

Useful for retiring tags or cleaning up one-off tags across the vault.

set_tag_color

Assigns a display color to a tag. Inputs: tag, optional color.

Supported colors: yellow, green, blue (cyan), pink, purple. Omit color to clear the assignment.

Useful for visually categorizing tags in the sidebar.

star_document

Stars a note. Useful for marking important notes or curating a shortlist of current work.

unstar_document

Removes a star from a note. Useful for cleaning up starred lists or marking work as no longer active.

Live Editor Tools

These work with what you currently have open in Outerline. They require Outerline to be running.

get_active_document

Returns the note you currently have open in Outerline.

Useful for grounding an agent in your current note.

get_selection

Returns the text you currently have selected.

Useful for "rewrite this", "summarize this", or "turn this into bullets".

insert_at_cursor

Inserts text at your current cursor position.

Useful for drafting into the active note, or inserting summaries, lists, or next steps.

replace_selection

Replaces the selected text.

Useful for rewriting, shortening, or reformatting.

Version History Tools

These let an agent browse, compare, search, and restore document snapshots. They work even if Outerline is not running.

list_versions

Lists version history snapshots for a document. Inputs: path or uuid, optional limit.

Each entry includes the version ID (timestamp string), word count, and whether it was a manual or auto save.

Useful for seeing how a note has evolved or picking a version to diff or restore.

get_version

Returns the full content of a specific snapshot. Inputs: path or uuid, version_id.

Useful for reading an older draft, reviewing what a note looked like at a point in time.

get_version_annotations

Returns the highlights, notes, and comments captured alongside a snapshot. Inputs: path or uuid, version_id.

Useful for seeing what was highlighted or commented on at that point in time.

diff_versions

Returns a unified diff between two versions. Inputs: path or uuid, version_id_a, optional version_id_b. If version_id_b is omitted, diffs against the current document.

Includes word count delta. Useful for understanding what changed between drafts.

search_version_history

Searches across all snapshots for a query string. Inputs: path or uuid, query.

Returns which versions contain the text, with surrounding context. Useful for answering "when did I have this section?"

find_deleted_content

Finds content matching a query that existed in previous versions but is absent from the current document. Inputs: path or uuid, query.

Useful for answering "what did I cut from this note?" or recovering removed passages.

restore_version

Restores a snapshot as the current document. Inputs: path or uuid, version_id.

The current state is auto-snapshotted before the restore, so the operation is always reversible. If Outerline is running, the editor refreshes automatically.

get_writing_timeline

Returns the word count progression over time for a document. Inputs: path or uuid.

Useful for understanding writing velocity, identifying productive sessions, or seeing how a note grew.

Resources

Outerline also exposes a few resources that give agents a quick overview of your library.