Automation and Claude (URL scheme + MCP)

Perchnote has two ways to drive it from outside the app: the perchnote:// URL scheme for anything that can open a URL, and a separate perchnote-mcp binary for Claude clients.

URL scheme (perchnote://)

Perchnote registers the perchnote:// URL scheme, which makes it scriptable from anything that can open a URL: Apple Shortcuts, Raycast, Stream Deck, Alfred, cron, or a plain shell. Opening a link never touches the network.

A few rules worth knowing:

• Titles are URL-encoded and capped at 200 characters. Control characters are stripped.
• Meeting IDs must be valid v4 UUIDs. Anything else is rejected.
• Unknown links are silently ignored.
• Calling record/start while a recording is already in progress is a no-op. So is record/stop while idle.

x-callback-url. Every verb accepts the standard x-callback-url companion params (x-success, x-error), and perchnote://x-callback-url/<verb> works as an alias for perchnote://<verb>. For security, callback URLs are restricted to shortcuts://x-callback-url/... only, which is the resume shape Apple Shortcuts itself supplies. Anything else (including shortcuts://run-shortcut and http(s)) is refused, so a webpage cannot use a callback to launder app launches through Perchnote.

Apple Shortcuts. Use the Open X-Callback URL action with perchnote://record/start?title=Standup. Shortcuts appends x-success itself and resumes the shortcut when Perchnote calls it back.

Raycast. Save a script command:

#!/bin/bash
# @raycast.schemaVersion 1
# @raycast.title Start Meeting Recording
# @raycast.mode silent
# @raycast.icon 🎙️
open "perchnote://record/start"

Stream Deck. Add a System → Website action with perchnote://record/start as the URL. One physical button to start recording.

Shell / anything else.

open "perchnote://record/start"
open "perchnote://record/start?title=Design%20Review"
open "perchnote://record/stop"
open "perchnote://meeting/c075ff8d-5e65-4087-bce7-ba0f4391e476"
open "perchnote://meeting/c075ff8d-5e65-4087-bce7-ba0f4391e476/transcript"
open "perchnote://search?q=roadmap%20speaker%3A%22Amy%22"

You almost never type a meeting UUID by hand. The mirrored markdown notes carry a perchnote://meeting/... link in their frontmatter, and tasks exported to Things include the meeting link in their notes, so a to-do always points back to where it came from.

Claude MCP server (perchnote-mcp)

perchnote-mcp is a separate read-only local binary that exposes your meeting database to MCP-aware Claude clients (Claude Desktop, Claude Code, and others). It speaks Model Context Protocol over stdio, so it opens no port and runs no network listener of any kind. The only process that can talk to it is the local client you configure to spawn it.

It exposes four tools, all read-only:

• search_meetings. Same filter grammar as in-app search (speaker:, folder:, before:/after:, quoted phrases, trailing-* prefix).
• get_meeting. Meeting metadata and notes by ID.
• get_transcript. The transcript for a meeting, with the speaker labels you have set.
• list_open_action_items. Every open action item across your meetings.

Build it. From a checkout of the Perchnote source, in src-tauri/:

cargo build --release --bin perchnote-mcp
# binary lands at src-tauri/target/release/perchnote-mcp

Configure Claude Desktop. Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "perchnote": {
      "command": "/path/to/perchnote/src-tauri/target/release/perchnote-mcp"
    }
  }
}

Configure Claude Code. One command:

claude mcp add perchnote /path/to/perchnote/src-tauri/target/release/perchnote-mcp

Database path. By default the binary reads ~/Library/Application Support/com.perchnote.app/perchnote.db. Point it elsewhere with --db <path> or the PERCHNOTE_DB environment variable. The binary refuses to open a database whose schema does not match the version it was built from, so rebuild it when you update Perchnote.

What it can never do. Write to your database (the connection is opened read-only at the SQLite level). Expose calendar attendee data (the attendees column is excluded from every tool output, enforced by test). Expose your secrets, your settings, or anything in the Keychain. Show soft-deleted (trashed) meetings.