Bear MCP Server

A Model Context Protocol server for Bear — the note-taking app for Apple devices. Gives AI assistants (Claude Code, Claude Desktop, etc.) full read/write access to your Bear notes.

Why

Bear has no official API, but it does have:

• An x-callback-url scheme for creating and modifying notes
• A SQLite database that's readable for querying notes

This server combines both: SQLite for fast, flexible reads; x-callback-url for safe writes that go through Bear's own sync engine.

Architecture

┌─────────────┐    stdio (JSON-RPC)    ┌──────────────────┐
│  MCP Client │◄──────────────────────►│  Bear MCP Server │
│  (Claude)   │                        │  (Python)        │
└─────────────┘                        └────────┬─────────┘
                                                │
                                    ┌───────────┴───────────┐
                                    │                       │
                                    ▼                       ▼
                              ┌──────────┐         ┌──────────────┐
                              │  SQLite  │         │  x-callback  │
                              │  (ro)    │         │  (open -g)   │
                              └────┬─────┘         └──────┬───────┘
                                   │                      │
                                   ▼                      ▼
                              ┌────────────────────────────────┐
                              │           Bear.app             │
                              │     (iCloud sync, storage)     │
                              └────────────────────────────────┘

Reads go directly to Bear's SQLite database (file:...?mode=ro). This is safe — we're a read-only consumer, and Bear treats the database as its own.

Writes go through Bear's x-callback-url scheme (bear://x-callback-url/...), which routes through Bear's own API layer. This ensures iCloud sync, conflict resolution, and data integrity are all handled by Bear itself.

All write operations use open -g (background) + show_window=no + open_note=no to run silently without stealing focus.

Requirements

• macOS (Bear is Apple-only; the SQLite path and open command are macOS-specific)
• Bear installed
• Python 3.10+
• mcp Python package (pip install mcp)

Installation

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "bear": {
      "command": "python3",
      "args": ["/path/to/bear/server.py"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "bear": {
      "command": "python3",
      "args": ["/path/to/bear/server.py"]
    }
  }
}

Other MCP clients

The server uses stdio transport. Launch it as a subprocess:

python3 server.py

Tools (15)

Read Tools (via SQLite)

#### bear_search Search notes by text content or tag.

Returns: note title, id, created/modified dates, and a text preview.

#### bear_read_note Read the full content of a note.

Returns: full note content with metadata (id, dates, pinned, archived status).

#### bear_list_tags List all tags.

#### bear_list_todos Find notes with todo checkboxes.

Returns: note title, id, count of completed and remaining todos.

Write Tools (via x-callback-url)

#### bear_create_note Create a new note.

#### bear_append_to_note Add text to an existing note.

#### bear_update_section Replace content under a specific header.

This is the most powerful write tool — it enables surgical updates to specific sections of a note without touching the rest.

#### bear_add_tags Add tags to a note.

#### bear_rename_tag Rename a tag across all notes.

#### bear_delete_tag Delete a tag (notes are kept, just untagged).

#### bear_trash_note Move a note to the trash.

#### bear_archive_note Archive a note.

#### bear_grab_url Save a web page as a Bear note. Bear handles the HTML-to-markdown conversion.

#### bear_add_file Attach a file (image, screenshot, PDF) to a note.

File size limit: ~750KB. Files are base64-encoded and sent via URL scheme, which has a practical limit around 1MB. For larger images, compress or resize first.

#### bear_create_from_template Create a new note from a template note.

Templates are convention-based — any note can be a template. The tool reads the note, strips its title and trailing tags, applies placeholder replacements, and creates a new note.

How It Works

SQLite Database

Bear stores all notes in a Core Data SQLite database at:

~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/Application Data/database.sqlite

Key tables:

• ZSFNOTE — all notes (title, text, dates, flags)
• ZSFNOTETAG — tag definitions
• Z_5TAGS — join table linking notes to tags

Timestamps use Core Data epoch (seconds since 2001-01-01 00:00:00 UTC), not Unix epoch. The server converts these to human-readable ISO 8601 format.

x-callback-url Scheme

Bear supports 16 URL scheme actions. Documentation: https://bear.app/faq/x-callback-url-scheme-documentation/

The server uses these actions for writes:

• /create — new notes
• /add-text — append, prepend, replace, section-targeted updates
• /add-file — file attachments (base64-encoded)
• /trash, /archive — note lifecycle
• /rename-tag, /delete-tag — tag management
• /grab-url — web clipping

All calls use open -g (macOS background open) to avoid stealing focus.

Title vs ID Resolution

When a title is provided for write operations, the server first looks up the note's unique identifier via SQLite. This avoids ambiguity if multiple notes share similar titles. The id parameter always takes precedence and is used directly.

Limitations

• macOS only — depends on Bear's SQLite path and macOS open command
• No write confirmation — x-callback-url doesn't return results to CLI callers (only to other apps via x-success). Write operations are fire-and-forget. The server verifies the note exists before writing, but can't confirm the write succeeded.
• File size limit — ~750KB for file attachments due to URL scheme length limits
• No encrypted note support — encrypted notes can't be read via SQLite (content is in ZENCRYPTEDDATA blob)
• Bear must be running — x-callback-url writes require Bear to be open (it can be in the background)

Example Prompts

Search my Bear notes for "project plan"

Read my "Meeting Notes" Bear note

Create a Bear note called "Sprint Retro" with sections for "What went well", "What didn't", and "Action items"

Append "- Completed the deploy" to my "Sprint Retro" note under the "What went well" section

Show me Bear notes with incomplete todos

Save this page to Bear: https://example.com/article

Attach the screenshot at ~/Desktop/screenshot.png to my "Bug Report" Bear note

Archive my "Old Project" Bear note

License

MIT