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