bear-mcp

What is bear-mcp?

bear-mcp is an MCP server that gives AI assistants (like Claude) full access to your Bear notes on macOS. It reads notes via Bear’s SQLite database (fast, works when Bear is closed), writes using Bear’s x-callback-url scheme, and locks/unlocks notes with AppleScript UI automation. It is for anyone who wants to integrate Bear notes into an AI workflow.

How to use bear-mcp?

Clone the repository and install with pip install -e ., then add the server to your MCP config (typically .mcp.json) using the command python with args pointing to mcp_server.py. For the bear_lock tool, grant Accessibility permissions in System Settings (one-time setup).

Key features of bear-mcp

• Search notes by text and/or tag
• Read a note’s full content
• List recently modified notes
• Create, prepend, append, replace, and trash notes
• Lock/unlock read-only status via AppleScript
• Read notes even when Bear is closed (SQLite)

Use cases of bear-mcp

• AI-assisted note-taking: capture ideas, meeting notes, or research directly into Bear with tags.
• Automated tagging: work around Bear’s broken add-tags URL action by writing inline #tags that Bear recognizes.
• Search and summarize: ask your AI to find and synthesize information across notes by text and tag.
• Lock finished work: prevent accidental edits by making notes read-only after review.

FAQ from bear-mcp

How does bear-mcp read and write notes?

Reads go through Bear’s SQLite database directly (fast, silent, works when Bear is closed). Writes use Bear’s x-callback-url scheme (opens Bear briefly, non-destructive). Lock/unlock uses AppleScript UI automation.

Does bear-mcp require Bear to be open?

Read operations work even when Bear is closed. Write operations require Bear to be open briefly. Lock/unlock requires Bear to be running and Accessibility permissions granted.

How are notes identified?

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

Why does bear_lock need Accessibility permissions?

Because bear_lock uses AppleScript to click Bear’s menu items, which macOS requires Accessibility access for. This is a one-time setup in System Settings.

Can I use the underlying library without the MCP server?

Yes. The BearNotesAPI Python class can be imported and used independently of the MCP server.