Perform full-text FTS5 search across cached saved posts.

Searches title, excerpt, publication name, author, and content text (content is only present for posts fetched via get_post_content). query uses SQLite FTS5 syntax; a malformed query falls back to a substring match. Date filters take ISO 8601 strings (e.g. "2026-01-31"). Allows filtering by publication name, audience tier (see list_audiences for cached values, e.g. "everyone", "only_paid"), original post date (published_at), saved date (saved_at), and read_state ('unread', 'in_progress', 'finished', 'unfinished' (unread + in_progress), or 'started' — a post is 'finished' once its high-water reading progress crosses a threshold, default 0.95).

List cached saved posts with pagination and optional publication/audience filters.

sort_by can be 'saved_at', 'published_at', 'read_progress', or 'minutes_remaining'. audience filters by tier (see list_audiences for cached values, e.g. "everyone", "only_paid"). read_state filters by reading progress: 'unread', 'in_progress', 'finished', 'unfinished' (unread + in_progress), or 'started' — a post is 'finished' once its high-water reading progress crosses a threshold, default 0.95.

Retrieve full cached post details, timestamps (published_at and saved_at), and content by URL, local ID, or Substack post ID.

content_text is empty until get_post_content has fetched the post.

Bookmark a Substack post remotely on Substack and save it to the local cache.

Requires an active authenticated Substack session (run 'substack-saved-mcp login' if expired). Confirmation comes from Substack's save API (keyed by the post's numeric ID, read from the page) or, failing that, from a best-effort bookmark-button click whose rendered state is checked. remote_confirmed=False means the post is still cached locally, but the tool could not verify the bookmark was actually created on Substack's side — a subsequent 'sync --force' will correct the local cache if the remote save didn't actually happen.

Unbookmark a Substack post remotely and soft-delete it in local cache.

Soft-deletion preserves post history while removing it from active search/list outputs. When the post's Substack ID is known (normally true after a sync), this calls Substack's real unsave endpoint directly and is reliably confirmed; otherwise it falls back to a best-effort DOM click (see save_post). remote_confirmed=False means the post was still soft-deleted locally, but the tool could not verify the unbookmark on Substack's side.

Fetch a saved post's full content, cleaned and formatted for LLM consumption.

Returns the cached content_text if a previous fetch already stored it, unless force_refetch is set. Otherwise fetches the post's page directly, extracts its body_html from Substack's server-rendered window._preloads blob, converts it to plain text (headings, list items, and links kept readable), and caches the result. Requires an active authenticated Substack session. If the content can't be located on the page (e.g. Substack changed how it embeds it, or the post is paywalled beyond this account's access), returns success=False with a message suggesting the caller run 'substack-saved-mcp inspect-network' while opening the post so the real content source can be captured.

List all publications in local cache with post counts.

List distinct audience tiers present in local cache with post counts.

Discovers actual values in use (e.g. "everyone", "only_paid") rather than a hardcoded enum, since Substack's audience values aren't officially documented and may vary or grow over time.

Return cache statistics, database path, and last sync run status.

Trigger incremental or full resync of saved posts from Substack account into local SQLite cache.

Incremental (default) stops early once it reaches already-cached posts, so older posts' reading progress isn't refreshed. force=True fetches the whole list, refreshes every post, and soft-deletes local posts no longer saved on Substack. Returns a SyncRun whose status is 'success', 'partial' (the fetch was truncated, e.g. by rate limiting, and reconciliation was skipped), 'auth_required' (run 'substack-saved-mcp login'), or 'failed'. Requires an active authenticated Substack session and can take minutes on large accounts.

Perform full-text FTS5 search across cached saved notes.

Searches body text, author name/handle, and (for restacks) the attached post's title. query uses SQLite FTS5 syntax. Allows filtering by author (name or handle) and original note date (posted_after/posted_before, ISO 8601 strings). Substack exposes no bookmark time for notes, so saved_at is always None and saved_after/saved_before match nothing.

List cached saved notes with pagination and optional author/restack filters.

sort_by can be 'posted_at' (when the note was posted) or 'saved_at' (always None for notes, so it gives no meaningful order). restacks_only limits results to notes that restack a post.

Retrieve full cached note details (author, body, engagement counts) by URL or local ID.

Bookmark a Substack note remotely on Substack and save it to the local cache.

Requires an active authenticated Substack session (run 'substack-saved-mcp login' if expired). remote_confirmed=False means the note is still cached locally, but the tool could not verify the bookmark was actually created on Substack's side — a subsequent 'sync --force' will correct the local cache if the remote save didn't actually happen.

Unbookmark a Substack note remotely and soft-delete it in local cache.

Soft-deletion preserves note history while removing it from active search/list outputs. remote_confirmed=False means the note was still soft-deleted locally, but the tool could not verify the unbookmark on Substack's side.

Fetch a saved note's full content, cleaned and formatted for LLM consumption.

Returns the cached body_text if a previous fetch already stored it, unless force_refetch is set. Otherwise fetches the note directly via Substack's reader API (no browser page needed) and caches the result. Requires an active authenticated Substack session.

Trigger incremental or full resync of saved notes from Substack account into local SQLite cache.

Incremental (default) stops early once it reaches notes already saved locally. force=True fetches the whole list and soft-deletes local notes no longer saved on Substack. Returns a SyncRun whose status is 'success', 'partial' (the fetch was truncated, e.g. by rate limiting, and reconciliation was skipped), 'auth_required' (run 'substack-saved-mcp login'), or 'failed'. Requires an active authenticated Substack session.