claude-desktop-extension-bear-notes

Purpose

This is an unofficial MCP server for the Bear notes app with specific design choices, aimed at enabling AI assistants to search, read, create, and update local Bear notes. It can be installed as a one-click extension for Claude Desktop, or used as a standalone npm package with any MCP-compatible client (such as Claude Code, Codex, Gemini, Cursor, Windsurf).

Main Capabilities

• Relevance-ranked search: Search is not limited to literal substring matching; it ranks results by relevance across titles, body text, and hierarchical tags, with context snippets, and supports combinable filters for tags, date ranges, and pinned-only.
• Direct reading: Read operations access Bear's SQLite database directly, with no need to open or run the Bear app when querying.
• Native writing: Writes are performed through Bear's own URL handler, are atomic, and are validated by Bear.
• Date search: Supports relative dates, such as "yesterday", "last week", "beginning of last month".
• Hierarchical tag management: Tags can be viewed as a tree structure with note counts, and tags can be renamed or deleted across the entire note library.
• Fine-grained writing: Content can be appended at a specified heading, or a section can be replaced, without rewriting the entire note.
• File attachments: Images, PDFs, and documents can be attached, with a maximum size of 25 MB; symlinks are rejected for security reasons.
• Local-first and privacy: No network calls, no telemetry, all processing is done locally on your Mac, using native node:sqlite with no third-party binaries.

Usage

Claude Desktop extension

Prerequisites: Bear app and Claude Desktop are installed. Download the latest bear-notes-mcpb-*.mcpb extension file from Releases, make sure Claude Desktop is running, and double-click the file; Claude Desktop should show an installation prompt. If double-clicking does not work, open Claude → Settings → Extensions → Advanced Settings → click "Install Extension". After that, you can ask Claude to search Bear notes, for example "Search my Bear notes for 'meeting'".

Standalone MCP server

Requires Node.js 24.13.0+, and you can add the server to your MCP configuration file. For more complete installation options and local development setup, see NPM.md.

Available tools

The server provides the following tools:

• bear-open-note: Read the full text of a Bear note by ID or title, including OCR text from attached images and PDFs.
• bear-create-note: Create a new note, with optional title, content, and tags.
• bear-search-notes: Find notes by relevance across titles, body text, and attachment OCR text, with support for tags, date ranges, and pinned-only filters.
• bear-add-text: Insert text at the beginning or end of a note, or within a specified heading section; requires the current revision token.
• bear-replace-text: Replace the note body or the content of a specific section; requires the current revision token.
• bear-add-file: Attach a local file (image, PDF, document) to a note; Bear will extract text via OCR to make it searchable; requires the current revision token.
• bear-list-tags: List all tags and note counts as a hierarchical tree.
• bear-find-untagged-notes: Find notes without tags.
• bear-add-tag: Add one or more tags to a note; requires the current revision token.
• bear-archive-note: Archive a note so it is removed from active lists but not deleted.
• bear-rename-tag: Rename a tag across the entire note library.
• bear-delete-tag: Delete a tag from all notes without affecting the notes themselves.
• bear-capabilities: Reports the current server mode (read-only or edit mode) and how to unlock more capabilities.

Note: write-type tools require passing the note's current revision token (i.e., the Revision: N line referenced in the previous response); using a stale revision will be rejected, with a prompt to first use bear-open-note to re-read before retrying.

Configuration

• Verbose logging: In Claude Desktop, go to Settings → Extensions → Configure → toggle "Debug Logging"; for standalone servers, set the environment variable UI_DEBUG_TOGGLE=true.
• New note convention: By default, when Bear creates notes via the API, it places tags at the bottom; enabling this option places tags after the title (separated by a divider). In Claude Desktop, toggle "New Note Convention" in Configure; for standalone servers, set UI_ENABLE_NEW_NOTE_CONVENTION=true.
• Edit mode: Off by default; when off, the server is fully read-only, andtools/list returns only the 4 read tools (bear-open-note、bear-search-notes、bear-find-untagged-notes、bear-list-tags) plus bear-capabilities. When enabled, all 8 write tools are unlocked. In Claude Desktop, toggle "Edit Mode" in Configure; for standalone servers, set UI_ENABLE_CONTENT_REPLACEMENT=true.

Use cases

• There are a very large number of notes, literal substring search is no longer sufficient, and you need to find the right note by relevance.
• You switch between multiple MCP clients and want to use a unified stdio transport without writing glue code for each client.
• You want to quickly query notes during a conversation without having to bring Bear to the foreground, or even without running Bear.
• You need to rename or delete tags across the entire note library, which is cumbersome to do through the Bear interface.
• You care about supply chain security and prefer a server with native node:sqlite, no network, and no remote fetching tools.

Limitations

• macOS only, because the Bear desktop version runs only on macOS.
• Unofficial project; the author calls it an "opinionated alternative."
• Reads access SQLite directly; writes are still done through Bear.
• Attachment size limit is 25 MB; symlinks are not accepted.
• Writes require a revision token; stale revisions are rejected.
• When using an AI assistant, data sent to the AI provider still leaves the local machine, which is outside the server's control.
• When installing the extension, Claude for Desktop may show a red warning that it "will be granted access to everything on your computer"; this is because Claude's warning system cannot distinguish access to a single file from access to all files; the extension actually only accesses Bear's local database.
• For specifics such as verbose logging, standalone installation, the more complete options in NPM.md, and local development setup, please refer to the project repository; the materials do not provide other pricing, cost, or platform information.