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.

Parameter	Type	Default	Description
term	string	null	Search string (matches title and body)
tag	string	null	Filter by tag (e.g. "work" or "work/projects")
limit	int	20	Max results

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

bear_read_note

Read the full content of a note.

Parameter	Type	Default	Description
title	string	null	Note title (partial match)
id	string	null	Note unique identifier (exact match, takes precedence)

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

bear_list_tags

List all tags.

Parameter	Type	Default	Description
limit	int	50	Max results

bear_list_todos

Find notes with todo checkboxes.

Parameter	Type	Default	Description
show_completed	bool	false	Include notes where all todos are done
limit	int	20	Max results

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

Write Tools (via x-callback-url)

bear_create_note

Create a new note.

Parameter	Type	Default	Description
title	string	required	Note title
text	string	null	Body content (markdown)
tags	string	null	Comma-separated tags
timestamp	bool	false	Prepend current date/time

bear_append_to_note

Add text to an existing note.

Parameter	Type	Default	Description
text	string	required	Text to add
title	string	null	Note title
id	string	null	Note identifier
mode	string	"append"	"append" or "prepend"
header	string	null	Target a specific ## Header
timestamp	bool	false	Prepend current date/time

bear_update_section

Replace content under a specific header.

Parameter	Type	Default	Description
text	string	required	New section content
header	string	required	Header name to target
title	string	null	Note title
id	string	null	Note identifier

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.

Parameter	Type	Default	Description
tags	string	required	Comma-separated tags
title	string	null	Note title
id	string	null	Note identifier

bear_rename_tag

Rename a tag across all notes.

Parameter	Type	Default	Description
name	string	required	Current tag name
new_name	string	required	New tag name

bear_delete_tag

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

Parameter	Type	Default	Description
name	string	required	Tag to delete

bear_trash_note

Move a note to the trash.

Parameter	Type	Default	Description
title	string	null	Note title
id	string	null	Note identifier

bear_archive_note

Archive a note.

Parameter	Type	Default	Description
title	string	null	Note title
id	string	null	Note identifier

bear_grab_url

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

Parameter	Type	Default	Description
url	string	required	Web URL to save
tags	string	null	Comma-separated tags
pin	bool	false	Pin to top

bear_add_file

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

Parameter	Type	Default	Description
file_path	string	required	Absolute path to the file
title	string	null	Note title
id	string	null	Note identifier
header	string	null	Insert under a specific header
mode	string	"append"	"append" or "prepend"

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.

Parameter	Type	Default	Description
template_title	string	required	Title of the template note
new_title	string	required	Title for the new note
replacements	string	null	Pipe-separated key=value pairs (e.g. {{date}}=2026-03-06|{{project}}=Trixie)
tags	string	null	Tags for the new 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