bear-mcp

bear-mcp

An MCP server that gives AI assistants (Claude, etc.) full access to your Bear notes on macOS. Search, read, create, edit, and lock notes — all from your AI workflow.

Why?

Bear has no official API. This project bridges the gap using two strategies:

• Reads go through Bear's SQLite database directly — fast, silent, works even when Bear is closed.
• Writes use Bear's x-callback-url scheme — opens Bear briefly for each operation, but reliable and non-destructive.
• Lock/unlock uses AppleScript UI automation — the only way, since Bear doesn't expose this in its URL scheme.

What can it do?

Tool	What it does
bear_search	Find notes by text and/or tag
bear_get	Read a note's full content
bear_recent	List recently modified notes
bear_tags	List all tags
bear_create	Create a new note
bear_prepend	Add text to the top of a note
bear_append	Add text to the bottom of a note
bear_replace	Replace the entire body of a note
bear_trash	Move a note to trash
bear_lock	Toggle read-only (lock/unlock)

Notes are identified by UUID (or the first 8 characters of one), not titles.

Setup

1. Install

git clone https://github.com/zmainen/bear-mcp.git
cd bear-mcp
pip install -e .

2. Add to your MCP config

In your project's .mcp.json (or equivalent):

{
  "bear-notes": {
    "command": "python",
    "args": ["/path/to/bear-mcp/mcp_server.py"]
  }
}

3. Grant Accessibility permissions (for lock only)

bear_lock uses AppleScript to click Bear's menu items. macOS will prompt you to grant Accessibility access the first time. This is a one-time setup in System Settings > Privacy & Security > Accessibility.

Use cases

AI-assisted note-taking. Have your AI assistant capture ideas, meeting notes, or research directly into Bear with proper tags.

Automated tagging. Bear's add-tags URL action is broken. This server works around it by writing inline #tags into note bodies, which Bear recognizes automatically. Nested tags like #project/docs work.

Search and summarize. Ask your AI to find and synthesize information across your notes — it can search by text, filter by tag, and read full content.

Lock finished work. Use bear_lock to make notes read-only after review, preventing accidental edits.

Library usage

The underlying Python library works independently of MCP:

from bear_app import BearNotesAPI

bear = BearNotesAPI()  # auto-detects Bear's database

notes = bear.search_notes("query", tag="project")
note = bear.get_note(note_id="83779062-...")
print(note.title, note.is_locked, note.locked_date)

bear.create_note(title="New note", text="body", tags=["project"])
bear.toggle_read_only(note_id=uuid)

Gotchas

• IDs are UUIDs, not row numbers. Bear's internals use ZUNIQUEIDENTIFIER.
• add-tags is broken in Bear's URL scheme. Use inline #tag text instead.
• Spaces must be %20, not +. Bear interprets + literally. The library handles this automatically.
• Lock requires Bear running and Accessibility permissions. It's UI automation under the hood — reliable but not invisible.
• Never write to the SQLite database. All writes go through Bear's URL scheme.

License

MIT — Zach Mainen, 2025